Start free →

Learn / Guides / ai-agent-manifest.json

Updated March 2026

ai-agent-manifest.json: Give AI Your Official Brand Identity

There's a difference between AI finding information about you and AI knowing your official position. This file is your canonical identity declaration — machine-readable, verifiable, and designed for the age of AI agents.

What Is ai-agent-manifest.json?

Your Official Declaration

A JSON file at /.well-known/ai-agent-manifest.json that declares who you are, what you do, and how AI should identify you.

Machine-Readable Identity

Not prose for humans. Structured data for AI agents — entity disambiguation, verified services, API endpoints, and companion file locations.

Without this file, AI models reconstruct your identity from fragments — third-party reviews, competitor comparisons, outdated articles, and whatever else was in the training data. The result is often wrong: misattributed features, incorrect categories, and conflated brand identities. Implementing an ai-agent-manifest.json is one of the technical foundations of Brand Authority.

The /.well-known/ directory is the established convention for machine-readable service discovery (used by Apple, Google, and Let's Encrypt). Placing your manifest here signals to AI agents that this is your official, canonical identity declaration.

You can see Optimly's own manifest as a reference for what a production file looks like.

What Problem It Solves

Without a manifest

AI reconstructs your identity from whatever it finds — third-party mentions, competitor comparison pages, old press releases. You have zero control over how models identify you. And when your brand name is common or similar to another company? Models conflate them.

With ai-agent-manifest.json

You declare your canonical identity in a machine-readable format that AI agents can discover at a well-known path. Entity disambiguation prevents conflation. Verified URLs let agents cross-reference claims. It's your brand passport for the AI web.

The Template

A production-ready template based on Optimly's own manifest. Replace the placeholder values with your brand's facts.

{
  "schema_version": "1.0",
  "name": "Your Brand Name",
  "legal_name": "Your Legal Entity Name, Inc.",
  "description": "One-sentence description of what your company does.",
  "url": "https://your-domain.com",
  "logo": "https://your-domain.com/logo.png",
  "founded": "YYYY",
  "headquarters": "City, State, Country",
  "category": "Your industry category",
  "topics": [
    "topic-1",
    "topic-2",
    "topic-3"
  ],
  "audience": [
    "Primary audience 1",
    "Primary audience 2"
  ],
  "value_propositions": [
    "Core value proposition 1",
    "Core value proposition 2",
    "Core value proposition 3"
  ],
  "services": [
    {
      "name": "Service or Product Name",
      "description": "What this service does",
      "url": "https://your-domain.com/product"
    }
  ],
  "entity_disambiguation": {
    "not_affiliated_with": [
      "Similar-sounding company or product"
    ],
    "also_known_as": [
      "Alternative name or abbreviation"
    ],
    "parent_company": null,
    "subsidiaries": []
  },
  "founders": [
    {
      "name": "Founder Name",
      "role": "CEO",
      "linkedin": "https://linkedin.com/in/founder"
    }
  ],
  "social_profiles": {
    "linkedin": "https://linkedin.com/company/your-brand",
    "twitter": "https://x.com/your-brand"
  },
  "api_endpoints": {
    "brand_profile": "https://your-domain.com/api/brand",
    "openapi_spec": "https://your-domain.com/openapi.json"
  },
  "companion_files": {
    "llms_txt": "https://your-domain.com/llms.txt",
    "llms_full_txt": "https://your-domain.com/llms-full.txt",
    "robots_txt": "https://your-domain.com/robots.txt",
    "sitemap": "https://your-domain.com/sitemap.xml"
  },
  "last_updated": "YYYY-MM-DD"
}

Design Decisions

Why the /.well-known/ path?

The /.well-known/ directory is defined by RFC 8615 as the standard location for machine-readable metadata files. It's where Apple discovers your app-site associations, where Let's Encrypt verifies domain ownership, and where security.txt lives.

By placing ai-agent-manifest.json here, you're following an established pattern that AI agents already know to check. It's discoverable without being linked from any page — agents navigate to it directly.

Why entity_disambiguation is critical

AI models conflate similarly-named brands more often than you'd expect. Optimly.ai vs Optimly.io. Stripe the payment company vs Stripe the paint brand. Without explicit disambiguation, models blend these identities — and once blended, it's extremely hard to separate them.

The not_affiliated_with field is your first line of defense. It costs you one line in a JSON file and prevents months of brand confusion.

Why include API endpoints?

API endpoints serve two purposes: they give AI agents verifiable URLs to confirm your claims (your brand profile API returns the same data the manifest declares), and they enable agentic workflows where AI systems can programmatically access your brand information.

As AI agents become more autonomous, they'll need structured endpoints — not just text files. The api_endpoints and companion_files fields prepare your brand for that future.

Common Mistakes

Putting it at the wrong path

The file must live at /.well-known/ai-agent-manifest.json — not at /ai-agent-manifest.json or /manifest.json. The .well-known directory is a convention for machine-readable service discovery, and it's where AI agents look first.

Omitting entity disambiguation

If your brand name could be confused with another company (and most can), the entity_disambiguation field is critical. Without it, AI models may conflate your brand with similarly-named entities — a problem that compounds over time.

Stale data that contradicts your site

A manifest that says 'analytics platform' while your homepage says 'intelligence platform' creates conflicting signals. Models notice contradictions and reduce confidence in both sources. Keep your manifest current.

No services or API links

The services and api_endpoints fields tell AI agents what your brand actually does — with machine-readable URLs they can verify. Without them, the manifest is identity without evidence.

The AI Discoverability Stack

Four files. One system. Together they make current brand information easier for AI systems to discover and retrieve. See the full series →

robots.txt — Front Door

Tells AI crawlers what they can access

llms.txt — Concierge

Token-efficient index of your best content

llms-full.txt — Deep Content

RAG-ready structured content for retrieval

ai-agent-manifest.json — Identity You are here

Machine-readable brand positioning

Implementation Checklist

  1. Step 1

    Download the ai-agent-manifest.json template

  2. Step 2

    Fill in your brand identity fields (name, description, category)

  3. Step 3

    Add entity disambiguation — who you are NOT

  4. Step 4

    List your services with descriptions and URLs

  5. Step 5

    Add API endpoints if you have public APIs

  6. Step 6

    Link your companion files (llms.txt, sitemap, etc.)

  7. Step 7

    Create the /.well-known/ directory if it doesn't exist

  8. Step 8

    Upload to /.well-known/ai-agent-manifest.json

  9. Step 9

    Validate the JSON (no trailing commas, valid syntax)

See What AI Believes About Your Brand

Your manifest declares who you are. But what are AI models actually telling your buyers? Search our directory to find out.

Search the AI Brand Index Check your business — free

What is AI Brand Reputation? Methodology Hal9 Case Study llms.txt

Don't want to maintain these files yourself?

Claim your profile in the AI Brand Index, and we generate, maintain, and serve your entire Discoverability Stack automatically. Your llms.txt stays current. Your manifest reflects your latest positioning. Your brand-feed updates when you update your Business Profile.

All served via our agentic brand API so AI models always have your latest truth.

Claim Your Profile → See a working example on our site