Hosting ai-catalog.json on every major platform

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

The ARD standard requires your catalog at exactly https://yourdomain.com/.well-known/ai-catalog.json. Here is how to put it there on each platform. In every case, generate and download your file first, then verify with the checker afterwards.

WordPress (self-hosted)

Via your host's file manager or FTP, create a folder called .well-known in the site root, the same level as wp-content, and upload the file into it. Some hosts hide dot-folders; enable "show hidden files". If your host blocks it, a rewrite rule in .htaccess can serve the file from elsewhere.

Cloudflare Pages, Netlify, Vercel, GitHub Pages

Add the file to your project at .well-known/ai-catalog.json inside the published output folder and redeploy. All four serve dot-folders from the build output without configuration. (GitHub Pages with Jekyll needs include: [".well-known"] in _config.yml.)

Shopify

Shopify does not let you upload root files directly. Options: use a proxy layer such as Cloudflare in front of your domain and serve the path with a Worker or redirect rule, or watch for Shopify's native support as ARD adoption grows. Some merchants use the theme's assets plus an URL redirect from the well-known path, but note that a redirect must land on a URL that still returns JSON.

Squarespace and Wix

Same situation as Shopify: no root file uploads today. The Cloudflare-in-front approach works for both: point your DNS through Cloudflare (free tier) and serve /.well-known/ai-catalog.json from a tiny Worker.

Plain server (nginx, Apache, anything)

Drop the file in your web root: /var/www/html/.well-known/ai-catalog.json. Confirm your server sends Content-Type: application/json; both nginx and Apache do this by default for .json files.

Verify, whatever the platform

Run your domain through the checker. The most common platform failure is the path returning your 404 page with HTTP 200, which agents read as "broken catalog". The checker tells you exactly what came back.

Frequently asked questions

The checker says my file is not valid JSON but I uploaded JSON.

Your platform is almost certainly serving an HTML error page at that path instead of your file. Open the well-known URL in a browser and look at what actually loads.

Can the file live somewhere else and redirect?

Agents follow standard HTTP redirects, so a redirect from the well-known path to a JSON file generally works, but serving it directly is safer.