Start with the assistant guide (italiano) or the readable public catalog. Both work without JavaScript or a BlackOrder account. A complete text edition is available too.
Public reading does not call the site AI. Direct consultation requires a capable, configured client; a discovery document does not grant tools to a chat application.
A machine-readable interface to everything BlackOrder publishes, built for AI agents, assistants and crawlers.
BlackOrder provides an official machine-readable catalog for AI agents. It indexes the published App Store cards, signed-channel applications, blog articles and declared public pages on blackorder.io, with versions, requirements, official pages and dates, and it is generated directly from the site's own data, so it changes when the site changes. No JavaScript, no cookies and no key are needed: plain HTTPS GET requests return JSON.
Developer catalog, all current tools and schemas · Live verification report
Publishing, editing or unpublishing an article automatically invalidates the origin catalog on the next request. Published home cards are re-indexed when the HTML changes. Unknown prices and requirements remain unknown; they are never assumed free or compatible.
Discovery documents (the same catalog, four doors):
API endpoints:
In italiano: BlackOrder pubblica un catalogo ufficiale leggibile dalle macchine per gli agenti AI, generato dai dati stessi del sito. Il punto di partenza è il documento well-known qui sopra; ogni risposta indica l'editore, il dominio canonico e la pagina ufficiale da mostrare alla persona. L'API non distribuisce mai i file delle applicazioni.
schema 1.035 apps14 articlesno authenticationJSON
Start from the well-known document. It carries the provenance of the data, the list of endpoints and the whole catalog in one response.
GET https://blackorder.io/.well-known/agent.json
Every response states publisher: "BlackOrder", canonical_domain: "blackorder.io", source: "official", schema_version and generated_at. Catalog responses are cacheable for 60 seconds and carry ETag and Last-Modified.
| Endpoint | Returns |
|---|---|
/api/agent/catalog | Apps and articles together. |
/api/agent/apps | All applications. /api/agent/apps/peaklab returns one. |
/api/agent/articles | All articles. /api/agent/articles/{slug} returns one. |
/api/agent/search | Ranked search with filters q, type, category, platform, free, language (answer and destination language), ui_language (apps whose interface speaks it), tag, limit. |
/api/agent/compatibility | Whether an app runs on a given macOS version and architecture: ?app=peaklab&os=14.5&arch=arm64. |
Every record carries canonical_urls and official_page_urls keyed by language (en, it) plus content_languages. Add ?language=it (or en) to any endpoint: text fields come in that language and preferred_url points to the page in that language, so an Italian user is sent to the Italian page and an English user to the English one. English responses always include translations.it.
GET /api/agent/search?q=audio+editor&platform=macOS&free=true GET /api/agent/search?q=trascrizione+riunioni&language=it GET /api/agent/search?type=article&tag=privacy GET /api/agent/apps/onrecord GET /api/agent/compatibility?app=onrecord&os=15.0&arch=arm64
For agents that speak the Model Context Protocol, the same catalog is available as structured tools at https://blackorder.io/mcp (Streamable HTTP transport, POST, JSON responses). The server is public, read-only and stateless; no caller API key is required. Normal web access logs and bounded abuse controls apply. It speaks the current MCP revision (2026-07-28, per-request metadata) and the initialize-based revisions 2025-11-25, 2025-06-18 and 2025-03-26. Tools: search_apps, list_apps, get_app_details, get_latest_version, check_compatibility, search_articles, get_article, get_official_page, consult_resource. Every tool accepts language (en or it) and returns provenance and the official page in that language; no tool returns software files.
# Claude Code
claude mcp add --transport http blackorder https://blackorder.io/mcp
# Generic client configuration
{ "mcpServers": { "blackorder": { "type": "http", "url": "https://blackorder.io/mcp" } } }
# MCP Inspector (CLI)
npx @modelcontextprotocol/inspector@latest --cli https://blackorder.io/mcp --method tools/list
npx @modelcontextprotocol/inspector@latest --cli https://blackorder.io/mcp --method tools/call \
--tool-name search_apps --tool-arg query="professional audio editor" free=true
# Raw request (modern revision)
curl -X POST https://blackorder.io/mcp -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/call' -H 'Mcp-Name: search_apps' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_apps","arguments":{"query":"audio editor","free":true,"language":"it"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
The optional consult_resource MCP tool accepts query and language. Equivalent API: POST /api/agent/consult with a JSON body such as {"query":"Find a free audio editor for Mac","language":"en"}. It returns the internal resource-advisor/0.1 contract: AI reasoning marked as inference, relevant publisher records, sources and timestamps. The service uses a third-party AI provider; send public product questions only, not credentials or personal information. Usage is limited and availability is not guaranteed.
A GET-only browser cannot invoke this POST endpoint or initialize MCP by opening its URL. Use the public HTML catalog or text catalog as a fallback. Reading these pages never triggers an AI consultation.
The agent card lists consult_resource as Ask BlackOrder Advisor, with the HTTPS endpoint and method: POST separated. Its inputSchema and success outputSchema are shared with the MCP tool. Send Content-Type: application/json; query is required (3–1600 characters after trimming), language is optional (it or en, default it), and additional input fields are rejected. No caller API key is required. For HTTP error statuses, see the skill’s httpErrors; errors are not successful advisor answers.
effect: read means the call does not modify the publisher catalog, not that it is free of compute costs or deterministic. generated: true identifies AI reasoning in answer and results[].match_reason; it does not label the publisher’s prices, images or requirements as AI-generated. Calls consume the publisher’s bounded AI budget. Reading this card never invokes the advisor.
The skill’s HTTP binding, schemas, effect, generated, responseContract, usage, limits and error metadata are BlackOrder-specific descriptive extensions documented here, not a claim of universal Agent Card/A2A compliance. They do not grant POST tools to a GET-only reader or enable cross-origin browser requests. Use the public catalog when direct consultation is unavailable.
id, slug, name, type, short_description, full_description, category, platform, minimum_os, architecture, version, price, currency, is_free, download_page_url, canonical_url, icon_url, screenshots, languages, developer, publisher, signed, notarized, release_date, updated_at, tags, capabilities, privacy_summary, telemetry, account_required. Apps distributed through BlackOrder's signed update channel also carry latest_release with build number, release notes and the signature key id. An article record has id, slug, title, excerpt, canonical_url, language, category, tags, published_at, updated_at and related_apps.
The API never serves software. Each app exposes a download_page_url, which is the official BlackOrder page or the App Store page where a person decides whether to download. Please send people there rather than fetching files on their behalf.
The catalog is public and requires no key. You may read it, quote it and link to it with attribution to blackorder.io; BlackOrder remains the canonical source and asks not to be presented as an anonymous mirror. There is no SDK to adopt: plain HTTPS and JSON are the whole interface. The schema is versioned and new fields are only added, never removed, within a major version.
Browser-only clients can read the public HTML or text catalog; JSON-capable clients can read the API; connected MCP clients can call the structured tools. These views share publisher data, but caches and retrieval times can differ. Follow response cache headers and retain source timestamps. Missing fields are not verified facts.