How to Publish an OpenAPI File AI Agents Can Find

An agent that wants to call your API has to know what it can ask for. An OpenAPI file answers that in one fetch: every path, every parameter, every response shape, in JSON a program can read. Publishing it takes about ten minutes if you already have the file, and the check that grades it (E2) is a pass or a miss with no partial credit for a file that exists but does not parse. This guide covers where to serve it, which version to write, how to advertise it, and how to prove it parses.

Quick summary

Short answer: serve an OpenAPI 3.1 JSON document at /openapi.json with a JSON content type, list your real API host in servers, and add a service-desc link so agents do not have to guess the path.

According to the OpenAPI Specification 3.1.2 (fetched 12 October 2026), it is RECOMMENDED that the entry document be named openapi.json or openapi.yaml. That is the whole reason /openapi.json is the path every scanner tries first.

What an agent does with the file

Think of the file as the menu a restaurant hands over before anyone orders. Without it, an agent reads your human-facing docs, guesses a parameter name, gets a 400 and tries again. With it, the agent reads the menu once and sends a correct request first time.

The spec sets a low bar for what counts as a document. In its own words, an OpenAPI description must contain at least one of paths, components or webhooks. A file with only openapi and info is valid JSON and useless, and AIScan treats that kind of file as a miss. A file with real paths is what an agent can act on.

AIScan's E2 check (the capability checks reference, verified on 12 October 2026) looks for /openapi.json, /openapi.yaml, /api/openapi.json, /.well-known/openapi.json, /swagger.json, or a service-desc link in your RFC 9727 API catalog. E2 has a weight of 3 and is marked recommended. On sites detected as pure content sites, the report calls it an optional improvement rather than a failure.

Who should skip this

If your site has no endpoints a stranger could call, there is nothing to describe. A brochure site, a blog, a store whose only API is the platform's own: skip E2 and spend the time on llms.txt and server-rendered HTML. A WordPress site already exposes /wp-json/, which is WordPress's own route index, not an OpenAPI file. If you only run a blog on WordPress, the useful files for you are llms.txt, robots rules and schema, and ThinkRank handles all three from one plugin and migrates from Rank Math, Yoast, AIOSEO and SEOPress. If you run a Shopify store, StoreSEO generates llms.txt from live products and collections. Neither of those publishes an OpenAPI file for an API you wrote yourself, which is what this guide is about.

Publish the file when you run your own API: a SaaS product, a headless backend, a public data endpoint, a booking or quote service.

Choose a version

Write 3.1. The spec site at spec.openapis.org lists 3.1.2 and 3.2.0 as published (fetched 12 October 2026), and the spec says tooling that supports OAS 3.1 should be compatible with all 3.1.x patch versions. AIScan's own reference file uses 3.1.0 and its docs describe the target as OpenAPI 3.1.

Two version traps:

• A swagger key at the top instead of openapi marks an older Swagger 2.x file. AIScan still looks for /swagger.json, but new files should use openapi.
• The openapi field is the spec version. info.version is your API's own version. Mixing them up is the most common first-draft mistake.

Path one: write the file by hand

Use this when you have a handful of endpoints and no framework that exports a spec.

1. Create a file named openapi.json.
2. Start with the three required top-level pieces: openapi, info (with title and version) and paths.
3. Add a servers array with your real, absolute API URL. The spec says that when servers is missing, the default is a single server with a url of /, which is relative to wherever the file was fetched and tells an agent nothing about a separate API host.
4. Describe each operation with a summary, its parameters and at least one response.
5. Serve the file from the site root as a static file with the content type application/json.

A minimal file that passes the check:

{
  "openapi": "3.1.0",
  "info": { "title": "Example Quote API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/quotes": {
      "get": {
        "summary": "List quotes",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "A list of quotes" } }
      }
    }
  }
}

Where the static file goes depends on your stack:

Path two: let your framework write it

If your API is built with a framework that already generates a spec, publishing is a setting, not a writing job.

1. Find the framework's export or docs-URL setting.
2. Confirm it produces OpenAPI 3.x, not Swagger 2.
3. Make the URL one of the paths E2 tries, or add a redirect from /openapi.json.
4. Re-export on every release so the file never describes last quarter's API.

FastAPI is the clean example. According to its docs (fetched 12 October 2026), the schema is served at /openapi.json by default, can move with the openapi_url parameter, and setting openapi_url=None turns it off along with the documentation pages that use it. If you set it to /api/v1/openapi.json, E2 will not find it, so add a link as described next.

Other frameworks vary by version, so check yours before copying a command from a blog post, including this one.

Advertise it so agents do not guess

A file at a guessable path passes E2. A file that is linked is found by agents that do not know your conventions. Add two pointers.

A Link header. The service-desc relation comes from RFC 8631. On nginx:

add_header Link '</openapi.json>; rel="service-desc"; type="application/json"' always;

I have not run that nginx line in this session (no nginx in the sandbox), so confirm it with curl -I after you reload.

An API catalog entry. RFC 9727 defines /.well-known/api-catalog. Add your spec as a service-desc entry. Our walkthrough, publish an API catalog agents can find, covers the full file, so this guide stays on the OpenAPI document itself.

AIScan's own setup shows the pattern. Fetched on 12 October 2026, aiscan.site/openapi.json returns 200 with application/json, declares 3.1.0, lists two paths and names https://aiscan.site as its server. The catalog at /.well-known/api-catalog returns application/linkset+json and lists that file first under service-desc. One honest gap: the Link header on the homepage has a service-desc entry that points at /api/scan (the SSE stream), not at the OpenAPI file, so an agent reading only headers would miss the spec and need the catalog.

Verify it parses

With AIScan

Run npx aiscan-cli yoursite.com, or paste the URL at aiscan.site. It is free and needs no account. Read these rows:

AIScan cannot judge whether your spec is accurate. It can find a file and confirm it is there. It will not notice that your spec describes an endpoint you removed in March. That part is a review job, and it is yours.

By hand

If you would rather check by hand, run this script. It tries each path E2 uses and refuses to count a soft 200 (an HTML page returned with status 200) as a pass.

#!/usr/bin/env python3
import json, sys, urllib.request, urllib.error

PATHS = ["/openapi.json", "/api/openapi.json", "/.well-known/openapi.json", "/swagger.json"]
UA = "Mozilla/5.0 (compatible; openapi-check/1.0)"

def fetch(url):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    try:
        with urllib.request.urlopen(req, timeout=15) as r:
            return r.status, r.headers.get("content-type", ""), r.read(5_000_000)
    except urllib.error.HTTPError as e:
        return e.code, e.headers.get("content-type", ""), b""

def main(site):
    base = "https://" + site.removeprefix("https://").strip("/")
    problems, found = [], False
    for p in PATHS:
        status, ctype, body = fetch(base + p)
        if status != 200:
            print(f"-    {p}: {status}")
            continue
        try:
            doc = json.loads(body)
        except ValueError:
            problems.append(f"{p}: 200 but not JSON ({ctype or 'no type'}), a soft 200")
            continue
        version = doc.get("openapi") or doc.get("swagger")
        if not version:
            problems.append(f"{p}: JSON without an openapi or swagger key")
        elif not any(k in doc for k in ("paths", "components", "webhooks")):
            problems.append(f"{p}: version {version} but no paths, components or webhooks")
        elif "json" not in ctype:
            problems.append(f"{p}: parses, but content-type is {ctype!r}")
        else:
            print(f"PASS {p}: {version}, {len(doc.get('paths', {}))} paths, {ctype}")
            found = True
    for m in problems:
        print("FAIL", m)
    return 0 if found and not problems else 1

if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

Save it as check_openapi.py and run python3 check_openapi.py yoursite.com. A pass prints the version and the path count and exits 0.

I ran it on 12 October 2026 against aiscan.site (PASS on /openapi.json: 3.1.0, 2 paths; the other three paths returned 404) and against a local test server built to fail. That server returned an HTML shell with status 200 for every unknown path, a {"hello":1} file at /openapi.json, and an openapi file with no paths at /swagger.json. The script reported all four as FAIL and exited 1. The soft 200 is the trap worth remembering: a status check alone calls an HTML page a pass.

Success thresholds, in order of strictness:

1. /openapi.json returns 200 and a JSON content type.
2. The body parses and has openapi and at least one of paths, components, webhooks.
3. A path that should not exist returns 404, not 200. Try /definitely-not-here.json.

If check 3 fails, your server answers everything with 200 and every other check in this guide is unreliable until you fix it.

When the file is there and agents still fail

Three failures show up after the file is live. Each has a first thing to try.

A related question is whether an agent can finish a job once it has found your API. That is a separate test, covered in how to test whether an AI agent can complete a task on your site, and it is worth running once the spec is live. The spec tells an agent what exists, and the test tells you whether the calls work. The wider set of well-known files is mapped in our well-known files corpus, with figures fetched from the live sites it measured.

Maintenance

• Regenerate the file in your release pipeline. A stale spec is worse than none, because an agent trusts it.
• Re-run the script after any change to caching, redirects or a CDN rule. A rule that rewrites unknown paths to the home page will turn your 404s into soft 200s.
• Keep the file public. If it contains internal-only routes, remove them before you serve it.

Next step

Scan your site at aiscan.site and read check:E2 and check:P1 in the Capabilities group. Then browse the other fixes in the AIScan guides, starting with the capability checks reference.