What is ai-catalog.json?

Last reviewed 2026-07-06 · Agent Ardvark field notes

ai-catalog.json is a small text file that lives at a fixed address on your website: https://yourdomain.com/.well-known/ai-catalog.json. It tells AI agents, in a format they can read reliably, what your site offers: your APIs, your tools, your services, your content.

It was defined in 2026 by the Agentic Resource Discovery (ARD) specification, co-authored by Google, Microsoft and Hugging Face, with collaborators including Cisco, GitHub, Nvidia, Salesforce and Snowflake.

Why it exists

AI assistants increasingly act as agents: they book tables, compare suppliers, research options and make purchases on a person's behalf. When an agent lands on a website today, it has to guess what the site offers by reading pages written for humans. That is slow and unreliable, so agents favour sites that describe themselves properly.

The comparison everyone reaches for: robots.txt told search crawlers what they could index, and sitemap.xml told them where everything was. ai-catalog.json plays the same role for AI agents. Sites that publish one can be discovered; sites that do not are, to an agent, a locked shop with no sign.

What it looks like

A minimal valid file has just two required fields, specVersion and entries, plus an optional host block naming the publisher:

{
  "specVersion": "1.0",
  "host": { "displayName": "Example Studio" },
  "entries": [
    {
      "identifier": "urn:air:example.com:api:bookings",
      "displayName": "Booking API",
      "type": "application/openapi+json",
      "url": "https://example.com/openapi.json",
      "description": "Check availability and book appointments.",
      "representativeQueries": [
        "book a session at Example Studio",
        "what slots are free on Friday"
      ]
    }
  ]
}

Each entry needs a unique identifier (a URN built from your domain), a displayName, a media type, and exactly one of url (a link to the resource's own description) or data (the description inline). See a full annotated example.

Do I need one?

If you want AI agents to be able to find, recommend or use your website: yes, eventually, and early adopters get the visibility head start. If your site is purely for human eyes and you would rather agents ignored it, you can skip it. Adoption is early: when we scanned twenty of the biggest tech companies in July 2026, only Hugging Face had published one.

Frequently asked questions

Where exactly does the file go?

At /.well-known/ai-catalog.json on your domain. The folder is literally named .well-known, with the dot. See our platform-by-platform hosting guide.

Is ai-catalog.json the same as llms.txt?

No. llms.txt is an informal convention for pointing language models at readable content. ai-catalog.json is part of a formal specification (ARD) with a JSON schema, backed by Google, Microsoft and Hugging Face, and describes machine-usable capabilities, not just content.

Does it affect my Google ranking?

Not directly, as of 2026. It affects whether AI agents can discover and use your site, which is a separate and growing channel.