BlackOrder for AI agents: an official machine-readable catalog

More and more of the people who find software do not browse for it: they ask. An assistant reads the web on their behalf, compares, and answers with a link. That assistant has a hard time with a site like ours. It has to guess what an app does from a marketing page, it does not know whether the version on the page is still current, and it cannot tell a free download from a paid one without reading three paragraphs. When it gets something wrong, the person on the other side gets a wrong answer with our name on it.

The fix is not to write better prose for machines. It is to publish the facts once, in a form a machine can read without guessing, from the same place the site itself reads them.

BlackOrder now provides an official machine-readable catalog for AI agents. The entry point is blackorder.io/.well-known/agent.json, a single document that says who BlackOrder is, lists the endpoints, documents the search parameters with examples, and carries the whole catalog: one record per application, with name, description, category, version, minimum macOS, architecture, price and whether it is free, whether it is signed and notarized, what it can do, what it does with your data, and the official page where a person downloads it; and one record per article of this blog, with its canonical address in English and Italian, its tags and dates, and the apps it relates to. The same data is also served as an agent card at agent-card.json, as a bare catalog at ai-catalog.json, and as a short plain-text summary at llms.txt.

Nothing in it is maintained by hand. Articles come from the blog's own database, versions and requirements from the signed update channels the apps themselves verify, and the App Store titles from the cards on the home page. Publish an app or an article and it appears; change a version and the record changes; remove something and it disappears, within a minute.

There is a search endpoint, /api/agent/search, with a free-text query and filters for type, category, platform, price, language and tag, returning ranked results that always carry the canonical BlackOrder URL. There are endpoints for the apps, the articles, a single app or article by slug, and a compatibility check that answers whether an app runs on a given Mac.

Every response states its provenance: publisher BlackOrder, canonical domain blackorder.io, source official, and the date the content last changed. The API never serves software. An agent can find and recommend an app, but the download happens on the official page, where the person decides. Discovery works the way the web already works: a link tag in the head of the home page and of every blog page, a Link header on every response, the agents page linked from the footer, robots.txt and the sitemap.

A few examples say more than a specification. Asking the search for a free professional audio editor for macOS returns PeakLab first, with its page on this blog. Asking for a free coding agent workspace for Mac returns Charlie. Asking for all free apps returns the live list. Asking for articles about AI and coding returns the ones that fit. Each answer includes the canonical page to show to the person.

The interface is deliberately plain: HTTPS and JSON, no SDK, no account, no key, responses cacheable for five minutes with ETag and Last-Modified, and a versioned schema that will only grow. The functions behind the endpoints are already shaped as tools, so an MCP server exposing search, app details, article, compatibility, latest version and official download page can follow without changing what is published here.

The human documentation, with the list of endpoints, the parameters and examples of queries, is at blackorder.io/agents.