{ "openapi": "3.1.0", "info": { "title": "BlackOrder Public Agent API", "version": "2.1.0", "description": "Provider-neutral HTTP interface. No automatic connection to consumer AI chats is implied. Apps, articles and public site pages share sources with MCP." }, "servers": [ { "url": "https://blackorder.io" } ], "paths": { "/api/agent/catalog": { "get": { "operationId": "list_catalog", "summary": "Read the indexed official catalog and coverage", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." } } } }, "/api/agent/apps": { "get": { "operationId": "list_apps", "summary": "List software", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." } } } }, "/api/agent/apps/{slug}": { "get": { "operationId": "get_apps", "summary": "Read one official apps record", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." }, "404": { "description": "Record not found." } } } }, "/api/agent/articles": { "get": { "operationId": "list_articles", "summary": "List articles", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." } } } }, "/api/agent/articles/{slug}": { "get": { "operationId": "get_articles", "summary": "Read one official articles record", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." }, "404": { "description": "Record not found." } } } }, "/api/agent/pages": { "get": { "operationId": "list_pages", "summary": "List public pages including Studio and services", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." } } } }, "/api/agent/pages/{slug}": { "get": { "operationId": "get_pages", "summary": "Read one official pages record", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." }, "404": { "description": "Record not found." } } } }, "/api/agent/search": { "get": { "operationId": "search_site", "summary": "Search public services/pages, apps and articles", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 500 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "app", "article", "page" ] } }, { "name": "language", "in": "query", "schema": { "type": "string", "enum": [ "en", "it" ], "default": "en" } } ], "responses": { "200": { "description": "Publisher data with source URLs and observation dates; missing facts are unknown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." } } } }, "/api/agent/consult": { "post": { "operationId": "consult_resource", "summary": "Ask the publisher-operated DeepSeek advisor; generated interpretation with cited sources", "description": "Read-only consultation. Consumes publisher AI budget. Send only the public question, never secrets or payment data. GET readers should use /agents/catalog or /llms-full.txt; opening this POST URL does not invoke AI.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 1600 }, "language": { "type": "string", "enum": [ "it", "en" ], "default": "it" } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Generated answer and publisher records; AI prose remains inference.", "content": { "application/json": { "schema": { "type": "object", "required": [ "contract", "status", "answer", "results", "generated_at" ], "properties": { "contract": { "const": "resource-advisor/0.1" }, "status": { "const": "ok" }, "answer": { "type": "object" }, "results": { "type": "array" }, "generated_at": { "type": "string" } }, "additionalProperties": true } } } }, "429": { "description": "Rate limit; respect Retry-After when supplied." }, "503": { "description": "Source temporarily unavailable." }, "400": { "description": "Invalid request" }, "403": { "description": "Origin not permitted" }, "405": { "description": "POST required" }, "413": { "description": "Body too large" }, "415": { "description": "JSON required" } } } }, "/api/agent/tools/consult_resource": { "post": { "operationId": "tool_consult_resource", "summary": "Chiedi all’agente del sito", "description": "Ask the BlackOrder site agent about its services, apps or articles. It uses DeepSeek to inspect the official catalog and returns recommendations, official images, requirements and source URLs. Read-only; AI commentary is explicitly inferred. Never send secrets, personal details or payment data.", "x-mcp-tool": "consult_resource", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 1600 }, "language": { "type": "string", "enum": [ "it", "en" ], "default": "it" } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "contract", "status", "answer", "results", "generated_at" ], "properties": { "contract": { "const": "resource-advisor/0.1" }, "status": { "const": "ok" }, "answer": { "type": "object" }, "results": { "type": "array" }, "generated_at": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/search_site": { "post": { "operationId": "tool_search_site", "summary": "Search the official site", "description": "Search services, Studio, contacts, public pages, applications and articles. For custom development or company questions search here, not only search_apps. Missing results do not prove a service is absent.", "x-mcp-tool": "search_site", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 500 }, "language": { "type": "string", "enum": [ "en", "it" ], "default": "en" }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true } } }, "required": [ "results" ] } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/read_site_page": { "post": { "operationId": "tool_read_site_page", "summary": "Read an official public page", "description": "Read the current published text of a page by its slug from search_site. Includes content date, hash, headings and truncation flag. No arbitrary URL fetching.", "x-mcp-tool": "read_site_page", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 160 }, "language": { "type": "string", "enum": [ "en", "it" ], "default": "en" } }, "required": [ "slug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "page" ], "properties": { "page": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/search_apps": { "post": { "operationId": "tool_search_apps", "summary": "Search BlackOrder apps", "description": "Ranked search over BlackOrder applications. Returns compact records with canonical_url and official_page_url (the page where a person downloads; files are never returned).", "x-mcp-tool": "search_apps", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Free-text query, e.g. \"professional audio editor\"." }, "platform": { "type": "string", "enum": [ "macOS", "iOS", "iPadOS" ], "description": "Platform filter; BlackOrder publishes macOS, iOS and iPadOS software." }, "category": { "type": "string", "enum": [ "audio", "video", "developer-tools", "network", "security", "system", "productivity", "utilities", "weather" ], "description": "App category." }, "free": { "type": "boolean", "description": "true = free apps only, false = explicitly paid apps only. Unknown prices match neither filter." }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Words that must appear in the app's capabilities (e.g. [\"transcription\"])." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "publisher": { "type": "string" }, "source": { "type": "string" }, "canonical_domain": { "type": "string" }, "total": { "type": "integer" }, "language": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true } } }, "required": [ "publisher", "source", "canonical_domain", "results" ], "additionalProperties": true } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/list_apps": { "post": { "operationId": "tool_list_apps", "summary": "List BlackOrder apps", "description": "All BlackOrder applications, optionally filtered by category, platform, price and language of the answer.", "x-mcp-tool": "list_apps", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "audio", "video", "developer-tools", "network", "security", "system", "productivity", "utilities", "weather" ], "description": "App category." }, "platform": { "type": "string", "enum": [ "macOS", "iOS", "iPadOS" ], "description": "Platform filter; BlackOrder publishes macOS, iOS and iPadOS software." }, "free": { "type": "boolean" }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "publisher": { "type": "string" }, "source": { "type": "string" }, "canonical_domain": { "type": "string" }, "total": { "type": "integer" }, "language": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true } } }, "required": [ "publisher", "source", "canonical_domain", "results" ], "additionalProperties": true } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/get_app_details": { "post": { "operationId": "tool_get_app_details", "summary": "Get app details", "description": "Full record of one app: description, version, requirements, capabilities, privacy facts, screenshots, official page. Identify it by app_id or slug (e.g. \"peaklab\", \"charlie\", \"onrecord\").", "x-mcp-tool": "get_app_details", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string" }, "slug": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true, "required": [ "canonical_url" ] } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/get_latest_version": { "post": { "operationId": "tool_get_latest_version", "summary": "Get latest version", "description": "Current version, build, release date, minimum macOS and release notes of an app distributed through BlackOrder's signed update channel, plus the official download page.", "x-mcp-tool": "get_latest_version", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "App id or slug." }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" } }, "required": [ "app_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true, "required": [ "canonical_url" ] } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/check_compatibility": { "post": { "operationId": "tool_check_compatibility", "summary": "Check compatibility", "description": "Whether an app runs on a given macOS version and CPU architecture.", "x-mcp-tool": "check_compatibility", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "description": "App id or slug." }, "os": { "type": "string", "description": "macOS version, e.g. \"14.5\"." }, "architecture": { "type": "string", "enum": [ "arm64", "x86_64" ], "description": "CPU architecture (Apple silicon = arm64)." }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" } }, "required": [ "app_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } }, "compatible": { "type": [ "boolean", "null" ] } }, "additionalProperties": true, "required": [ "canonical_url" ] } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/search_articles": { "post": { "operationId": "tool_search_articles", "summary": "Search The Dark Codex articles", "description": "Ranked search over BlackOrder's blog articles (English and Italian). Each result carries the canonical article URL in the requested language.", "x-mcp-tool": "search_articles", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "category": { "type": "string", "enum": [ "software", "essay" ], "description": "software = article about a BlackOrder app; essay = other writing." }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags that must all be present." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "publisher": { "type": "string" }, "source": { "type": "string" }, "canonical_domain": { "type": "string" }, "total": { "type": "integer" }, "language": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true } } }, "required": [ "publisher", "source", "canonical_domain", "results" ], "additionalProperties": true } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/get_article": { "post": { "operationId": "tool_get_article", "summary": "Get article", "description": "One article by article_id (numeric) or slug, with summary, excerpt, tags, dates, related apps and canonical URLs in English and Italian.", "x-mcp-tool": "get_article", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "article_id": { "type": [ "string", "integer" ] }, "slug": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true, "required": [ "canonical_url" ] } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/tools/get_official_page": { "post": { "operationId": "tool_get_official_page", "summary": "Get official page", "description": "The official BlackOrder page (or App Store page) for an app or article, in the requested language. This is where a person reads more and, for apps, decides whether to download. The API never serves files.", "x-mcp-tool": "get_official_page", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content_id": { "type": "string", "description": "App id/slug or article slug." }, "language": { "type": "string", "enum": [ "en", "it" ], "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.", "default": "en" } }, "required": [ "content_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Same structured data as MCP structuredContent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_url": { "type": "string", "format": "uri" }, "official_page_url": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "minimum_os": { "type": [ "string", "null" ] }, "architecture": { "type": [ "array", "null" ], "items": { "type": "string" } }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "is_free": { "type": [ "boolean", "null" ] }, "signed": { "type": [ "boolean", "null" ] }, "notarized": { "type": [ "boolean", "null" ] }, "facts": { "type": "object", "additionalProperties": { "type": "object", "required": [ "value", "source", "verified_at", "freshness", "confidence", "type" ], "properties": { "value": {}, "source": { "type": "object", "required": [ "url", "publisher", "type" ], "properties": { "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" }, "type": { "type": "string" } } }, "verified_at": { "type": "null" }, "freshness": { "type": "object", "properties": { "retrieved_at": { "type": "string", "format": "date-time" }, "max_age_seconds": { "type": "integer" } } }, "confidence": { "enum": [ "publisher_declared", "unknown" ] }, "type": { "const": "publisher_statement" }, "verification_scope": { "type": "string" } } } } }, "additionalProperties": true, "required": [ "canonical_url" ] } } } }, "400": { "description": "Invalid arguments or operation could not resolve a resource." }, "403": { "description": "Advisor browser origin not allowed." }, "429": { "description": "Usage limit; retry later." }, "503": { "description": "Source/provider unavailable." } } } }, "/api/agent/interfaces": { "get": { "summary": "Interface catalog", "responses": { "200": { "description": "Interface catalog", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/agent/skills": { "get": { "summary": "Machine-readable skills", "responses": { "200": { "description": "Machine-readable skills", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/agent/status": { "get": { "summary": "Periodic public verification report", "responses": { "200": { "description": "Periodic public verification report", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }