ai-catalog.json Explained: Agentic Resource Discovery for Business Websites (2026)
A new file has started appearing on websites in 2026: ai-catalog.json, now joined by ard.json. Google’s PageSpeed Insights has begun checking for it, and you may have seen it mentioned alongside llms.txt as something websites “need for AI”.
This guide explains what the file actually is, who created it, what reads it today, and whether your business website should have one. We have published one on this site, so the evidence below includes what our own server logs show about who requests it.
The short answer: ai-catalog.json is a menu of tools an AI agent can use, not a list of pages. It is worth having if your website offers something an agent can actually call, such as a booking check, a price lookup or a public API. It is not a search ranking factor, and nothing we have found shows that ChatGPT, Claude or Google Search read it today.
What ai-catalog.json is, in plain English
AI agents are AI systems that do things on your behalf: check availability, compare prices, fill in a form, book a slot. To do that on a website, an agent needs to know what the website offers and how to use it.
An AI catalog is a small file, published on your own domain, that lists those offerings in a format software can read. Each entry says what the resource is, what kind of thing it is, and where its technical description lives. That description is usually an OpenAPI file (for a normal web API) or a server card for an MCP server, a common way of connecting tools to AI assistants.
The file lives at a fixed, predictable address on your domain:
https://yourdomain.co.za/.well-known/ai-catalog.json- and, under the newest version of the specification,
https://yourdomain.co.za/.well-known/ard.json
The /.well-known/ folder is a long-standing web convention for files that software looks for automatically.
How it differs from robots.txt, sitemaps and llms.txt
It sits alongside files you may already know, and does a different job from each of them.
| File | What it says | Who it is for |
|---|---|---|
| robots.txt | Where crawlers may and may not go | Search and AI crawlers |
| sitemap.xml | Which pages exist | Search engines |
| llms.txt | A plain summary of the site and its key pages | Large language models |
| ai-catalog.json / ard.json | Which tools or services an agent can use, and where each is described | AI agents and agent registries |
The important difference: robots.txt, sitemaps and llms.txt are all about reading your content. An AI catalog is about doing something with your website. It is not a page index, and listing your pages in it is a misuse of the format. Our guide to llms.txt covers the reading side.
Where it came from: a verified timeline
| Date | What happened |
|---|---|
| 29 October 2025 | The AI Catalog working repository is created on GitHub, as a temporary Linux Foundation project in which people from several AI protocol groups work on “a common AI Catalog standard for discovering heterogeneous AI artifacts”. |
| 19 May 2026 | The Agentic Resource Discovery (ARD) specification repository is created, under the Apache 2.0 licence. |
| 17 June 2026 | Google announces ARD on the Google Developers Blog, describing it as “built upon the foundational AI Catalog data model”. InfoQ names Microsoft, GitHub, Hugging Face, Cisco, Databricks, GoDaddy, NVIDIA, Salesforce, ServiceNow and Snowflake as partners. Hugging Face launches its reference implementation, the Discover Tool, the same day. |
| 26 August 2026 | ARD version 0.91 is published with the status “Proposal”. Its authors are Junjie Bu (Google), R.V. Guha (Microsoft) and Shaun Smith (Hugging Face). The main address becomes /.well-known/ard.json, and ai-catalog.json becomes the predecessor that consumers “MAY additionally consult”. |
| 18 September 2026 | Google’s Lighthouse testing tool, version 13.5.0, adds an audit that validates the catalog, grouped with its llms.txt audit. |
| 25 September 2026 | PageSpeed Insights runs Lighthouse 13.5.0 and shows a new “Agentic Browsing” category that includes the check “ai-catalog.json schema is valid”. We confirmed this on our own site. |
Two things stand out. This is very recent: the whole public history is a few months long. And it is still a draft. The AI Catalog repository describes itself as temporary, pending “a permanent location” and “a permanent governance model”, and ARD’s own status line reads “Proposal”.
Who actually reads it today
The honest answer is: very few systems, and not the ones most business owners have in mind.
Agent registries. ARD’s design is that registries, which it describes as “search engines for the agentic web”, crawl published catalogs and make them searchable. Google says native ARD support will come to the Agent Registry in its Gemini Enterprise Agent Platform “in the coming months”. InfoQ reported early implementations in GitHub’s Agent Finder in Copilot and Hugging Face’s Discover Tool.
Testing tools. Lighthouse and PageSpeed Insights now fetch the file and check that it is valid. According to Search Engine Journal’s report on the release, the Lighthouse audit looks, in order, for an Agentmap line in robots.txt, then a rel="ai-catalog" link on the page, then the same relation in the HTTP Link header, and finally the file at /.well-known/ai-catalog.json. If none exists, the audit is marked not applicable rather than failed.
What our own logs show. We published our catalog on 23 September 2026 and checked the server logs for every request to it. Apart from our own checks, the only software that requested it was Chrome-Lighthouse, the engine behind PageSpeed tests: 13 requests. No ChatGPT, Claude, Perplexity, Google Search or Bing crawler asked for it. For comparison, over the same September logs our llms.txt was requested by Lighthouse, Meta’s crawler, Bingbot, and about once each by GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot and Googlebot.
The site sits behind Cloudflare, which answers some requests from its cache before they reach the server, so these counts are a floor rather than a complete census. But the pattern is clear. Today the catalog is read by testing tools and agent registries, not by the AI search assistants people use every day.
Does ai-catalog.json help SEO?
There is no evidence that it does. Search Engine Journal’s report on the Lighthouse audit notes that “it is not tied to Google Search anywhere in the release notes”, and nothing we found from Google, Microsoft or the AI assistant companies says the file affects rankings or citations.
The Lighthouse category it sits in does not even produce a 0 to 100 score. It shows a pass ratio instead, and PageSpeed describes the category as “still under development and subject to change”.
So treat any claim that an AI catalog will get you ranked or cited in ChatGPT with suspicion. What still drives visibility in AI search is what always has: pages that answer real questions clearly, accurate structured data, and a site that crawlers can actually reach. Our guide to how AI search engines choose which websites to cite goes into that.
Should your business website have one?
It depends on whether your website offers something an agent can use.
Worth publishing a proper entry if you have:
- A public API, for example stock, pricing or availability.
- A booking or availability check an agent could query.
- A calculator, checker or lookup tool with a documented endpoint.
- An MCP server or AI agent of your own.
Nothing to list if your site is information only. For most brochure websites there is no agent-callable tool. You can still publish a catalog with an empty list of entries, which is valid and costs almost nothing, but it tells agents nothing new. Never invent an entry to make the file look busy, and never list pages, products or blog posts as entries.
Never list anything private. Admin tools, login or payment endpoints, and internal connectors do not belong in a public file, however convenient it might seem.
What goes in the file
This is the catalog on our own site, which lists the free South African domain availability checker behind our domain checker tool:
{
"specVersion": "1.0",
"host": {
"displayName": "JWD Website Design",
"identifier": "jwd.co.za",
"documentationUrl": "https://www.jwd.co.za/llms.txt"
},
"entries": [
{
"identifier": "urn:air:jwd.co.za:api:domain-check",
"displayName": "South African domain availability checker",
"type": "application/vnd.oai.openapi+json",
"url": "https://www.jwd.co.za/openapi/domain-check.json",
"description": "Checks whether a domain name is available to register...",
"representativeQueries": [
"is example.co.za available to register",
"check if a .co.za domain name is taken"
]
}
]
}The entry is shortened here for reading. What the key fields do:
- specVersion and entries are required.
- host names the publisher. The specification calls a catalog with a host block a “Discoverable Catalog”.
- identifier is a unique name for the entry, in the recommended format
urn:air:{domain}:{namespace}:{name}. - type says what kind of resource it is, as a media type. Here it is an OpenAPI description.
- url points to that description. An entry must have either a
urlor inlinedata, never both. - representativeQueries is a set of example questions the resource can answer, which ARD registries use for search.
A third level of the specification, a “Trusted Catalog”, adds signed trust information about identity and provenance. Few publishers need it yet.
Getting the details right
- Publish both addresses. Lighthouse checks
ai-catalog.json, and ARD 0.91 looks forard.json. Serving both, with the same entries, covers both. - Serve the right content type:
application/ai-catalog+json. - Allow cross-origin reads with the header
Access-Control-Allow-Origin: *. Validators run in the browser and report “catalog file could not be loaded” without it, even when the file is perfect. - Advertise it with a
Linkheader usingrel="ai-catalog", or a<link rel="ai-catalog">tag on your pages. - Leave
Agentmap:out of robots.txt for now. The ARD specification lists it as a discovery method, and the Lighthouse catalog audit looks for it, but Lighthouse’s own robots.txt check flags it as an “Unknown directive” and marks the file invalid, which lowers your SEO score. We added it to our own robots.txt and saw exactly that on 25 September 2026, so we took it out. The Link header and the/.well-known/address are enough. - Validate it against the official schema, not by eye. Then run PageSpeed Insights and look for “ai-catalog.json schema is valid” under Agentic Browsing.
- Describe tools from their real, tested behaviour. We test our domain checker by calling it exactly as its OpenAPI file describes and checking the answers against that file’s schema.
A common mistake: putting the file at the root of the site, as /ai-catalog.json, instead of inside /.well-known/. Software looks in /.well-known/, so a file at the root will not be found.
What else is in the Agentic Browsing category
The same PageSpeed category checks whether your page’s accessibility tree is well formed, whether the layout stays stable, and whether your llms.txt follows recommendations. It also lists WebMCP checks. WebMCP is a separate proposed standard, currently in trial in Chrome, that lets a web page describe actions an AI agent in the browser can take, such as filling in a form. Most sites will see those checks as not applicable for now.
The pattern is the same across all of it: these are early standards for AI agents that act, not just read, and the tools to test them are arriving before most agents actually use them.
The bottom line
- ai-catalog.json and ard.json list tools an AI agent can use on your domain. They are not page indexes and not SEO files.
- The standard is months old and still a draft, backed by Google, Microsoft, Hugging Face and others.
- PageSpeed Insights now checks it, but in a category with no score, and it is not tied to Google Search.
- Publish one if you have a real public tool. If you do not, an empty catalog is harmless, but do not expect it to change anything.
If your website does have something an agent could use, such as a booking check, a quote calculator or a product lookup, we can build the endpoint, document it properly and publish the catalog as part of our SEO and AI search work. Our agent-ready website checklist and AEO and AI search guide cover the rest of what makes a business visible to AI. Request a quote and tell us what your site does.
Frequently Asked Questions
What is ai-catalog.json?
It is a machine-readable file, published at /.well-known/ai-catalog.json on a website’s domain, that lists the tools and services an AI agent can use there, such as a public API or an MCP server. Each entry points to that resource’s own technical description.
What is the difference between ai-catalog.json and ard.json?
ard.json is the newer name. Agentic Resource Discovery version 0.91, published on 26 August 2026, makes /.well-known/ard.json the main address and treats ai-catalog.json as its predecessor. Lighthouse still checks ai-catalog.json, so publishing both with the same entries is the safest choice.
Does ai-catalog.json improve my Google rankings?
There is no evidence that it does. The Lighthouse audit that checks it sits in a category without a score, and reporting on the release notes it is not tied to Google Search.
Do ChatGPT and Claude read ai-catalog.json?
We found no evidence that they do today. In our own server logs, the only outside software that requested our catalog was Chrome-Lighthouse. The systems built to read catalogs are agent registries, such as Hugging Face’s Discover Tool and Google’s planned Agent Registry support.
Is ai-catalog.json the same as llms.txt?
No. llms.txt is a plain summary of your content for language models to read. ai-catalog.json lists tools an agent can call. A website can have both, and they do different jobs.
Does every website need an AI catalog?
No. It is only useful if your website offers something an agent can use. An information-only website can publish an empty catalog, which is valid, but it has nothing to advertise.
