What is ai-plugin.json?

ai-plugin.json is the manifest file that exposes your site or API as a tool that AI agents can call. It lives at /.well-known/ai-plugin.json and points to your OpenAPI spec, logo, and contact info.

Do I need an API to publish one?

Yes — ai-plugin.json describes a callable API. If you only have a marketing site, you want llms.txt instead. If you have any HTTP endpoints worth exposing (search, lookups, actions), an ai-plugin.json is worth publishing.

Where do I host the file?

Always at https://yourdomain.com/.well-known/ai-plugin.json. The path is part of the spec — agents look there directly.

What auth types are supported?

'none' for fully public APIs, 'service_http' for a bearer token you provide, 'user_http' for per-user tokens, and 'oauth' for the full OAuth flow.

Does schema markup guarantee an AI citation?

No. Structured data can reduce ambiguity and improve attribution, but citation also depends on crawl access, content quality, relevance, authority, freshness, and the retrieval system used for the query.

Is JSON-LD better than microdata?

JSON-LD is usually easier to generate, maintain, and validate without mixing attributes into visible HTML. The important requirement is that the markup accurately describes content visitors can see.

Can FAQ schema contain answers hidden from visitors?

It should not. The questions and answers represented in FAQPage markup must match visible page content. Hidden or contradictory answers create a factual-parity problem and may violate search feature guidelines.

Should every page have Organization schema?

A stable Organization entity can be referenced sitewide, but avoid duplicating conflicting full definitions. Define the organization consistently and reference its stable @id from relevant pages.

How often should JSON-LD be audited?

Audit after template, CMS, pricing, author, product, or navigation changes, and include structured-data validation in routine releases. Time-sensitive properties should update from the same source as visible content.

ai-plugin.json Generator

Expose your API as a discoverable tool that AI agents can call. Built from the OpenAI plugin spec.

Quick answer

ai-plugin.json is a legacy plugin manifest format. This generator creates a manifest for consumers that explicitly support it; publishing one does not make an API automatically discoverable or callable by current assistants. Check the target platform's current integration and authentication requirements.

Name (human)

Name (model identifier)

Description for humans

Description for the model

OpenAPI spec URL

Logo URL

Contact email

Legal info URL

Auth type

Generated ai-plugin.json

{
  "schema_version": "v1",
  "name_for_human": "Acme Search",
  "name_for_model": "acme_search",
  "description_for_human": "Search Acme's documentation and product catalog.",
  "description_for_model": "Use this plugin to answer user questions about Acme products, pricing, and docs. Always cite the returned URL.",
  "auth": {
    "type": "none"
  },
  "api": {
    "type": "openapi",
    "url": "https://acme.com/openapi.yaml"
  },
  "logo_url": "https://acme.com/logo.png",
  "contact_email": "support@acme.com",
  "legal_info_url": "https://acme.com/legal"
}

Why publish an ai-plugin.json?

As AI agents start booking, searching, and transacting on behalf of users, your API needs a manifest they can discover. ai-plugin.json at /.well-known/ is the standard entry point.

Two key descriptions

description_for_human — what a user sees in a plugin store
description_for_model — instructions the LLM reads to decide when to call you

The model description matters most. Be explicit about when to use the plugin and how to present results — including any required citation behavior.

Structured content: connect page information to matching data fields.

Using ai-plugin.json Generator

What does structured data do for AI search?

JSON-LD gives machines an explicit graph of the page: who published it, what entity it describes, when it changed, and how its parts relate. That reduces ambiguity during extraction and attribution. It does not force an engine to crawl, trust, rank, or cite the page, so structured data belongs after access and visible content are correct. Treat structured data as a factual label on visible content. If a visitor cannot verify a claim on the page, do not add that claim only to JSON-LD.

What is a safe implementation workflow?

Generate JSON-LD from the same source of truth that renders the visible page. This prevents pricing, availability, dates, FAQ answers, and authorship from diverging. Server-render the script in the final HTML, escape serialized values safely, and avoid adding multiple contradictory entities from plugins and custom code.

How do you measure the value of schema for AI visibility?

Measure whether engines identify and describe the entity more accurately after markup is corrected. Track validation coverage, extraction errors, search enhancements where applicable, crawler visits, and citation accuracy for a fixed prompt set. Do not attribute a visibility change to schema when content, links, or crawl access changed at the same time.

Which schema types should you use?

Page purpose	Primary type	Critical properties
Company or brand	Organization	name, url, logo, sameAs
Editorial content	Article or BlogPosting	headline, author, datePublished, dateModified
Named expert	Person	name, jobTitle, affiliation, sameAs
Product or software	Product or SoftwareApplication	name, brand, offers, operatingSystem where relevant
Visible questions and answers	FAQPage	Question and acceptedAnswer matching the page
Visible ordered procedure	HowTo	name and complete ordered steps

Which structured-data mistakes cause the most harm?

Markup clarifies visible facts; it should never invent facts or hide content from visitors.
Organization, Person, Article, Product, FAQPage, and HowTo solve different entity questions.
Stable @id and sameAs references help connect the same entity across pages.
Rich-result eligibility and AI citation visibility are separate outcomes.
Validation must cover syntax, vocabulary, factual parity, and rendered production HTML.

How do you build a consistent entity graph?

1
Identify the page's main entity
Choose the most specific type that matches the visible purpose of the page.
2
Map visible facts
List the properties visitors can verify and omit unsupported or private claims.
3
Connect stable identities
Reuse organization and person @id values and carefully selected sameAs references.
4
Render JSON-LD from shared data
Generate markup from the same content source as the visible page to prevent drift.
5
Validate in production
Check syntax, vocabulary, parity, and the final server-rendered response after deployment.

Want the full picture?

OptimAIze checks structured data, content, crawler access and answer-readiness to help you investigate concrete issues. Technical improvements do not guarantee AI citations.

Run a full GEO + AEO scan on your site

Frequently asked questions

What is ai-plugin.json?: ai-plugin.json is the manifest file that exposes your site or API as a tool that AI agents can call. It lives at /.well-known/ai-plugin.json and points to your OpenAPI spec, logo, and contact info.
Do I need an API to publish one?: Yes — ai-plugin.json describes a callable API. If you only have a marketing site, you want llms.txt instead. If you have any HTTP endpoints worth exposing (search, lookups, actions), an ai-plugin.json is worth publishing.
Where do I host the file?: Always at https://yourdomain.com/.well-known/ai-plugin.json. The path is part of the spec — agents look there directly.
What auth types are supported?: 'none' for fully public APIs, 'service_http' for a bearer token you provide, 'user_http' for per-user tokens, and 'oauth' for the full OAuth flow.

Related free tools

Each one covers a different signal AI engines read before they cite a site.

All free tools GEO & AEO guides AI search answers Glossary