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.

What is `ai-plugin.json` and why is it important for my API?

`ai-plugin.json` is a standardized manifest file that acts as a blueprint for AI agents (like those powering ChatGPT or Gemini) to discover and understand your API. It's crucial because it enables your services to be callable tools within AI ecosystems, significantly expanding your API's reach and utility by allowing LLMs to programmatically interact with it on behalf of users.

Where exactly must the `ai-plugin.json` file be hosted?

The `ai-plugin.json` file must be hosted precisely at the `/.well-known/ai-plugin.json` path relative to your domain. For instance, if your domain is `example.com`, the file should be accessible at `https://example.com/.well-known/ai-plugin.json`. This standardized location is vital for AI crawlers to reliably find and index your plugin manifest.

What is the purpose of `description_for_model` compared to `description_for_human`?

`description_for_model` provides a concise, action-oriented summary specifically for the LLM to understand when and how to call your API (e.g., "Get current weather data for a location"). `description_for_human` is a user-friendly, longer description displayed to human users in plugin marketplaces or directories. The former drives AI invocation, the latter informs user choice.

What authentication types are supported in `ai-plugin.json`?

The `ai-plugin.json` standard supports several authentication types: `none` for unauthenticated APIs, `oauth` for OAuth 2.0 client credentials flow, and `service_http` for API key-based authentication (either via a Bearer token in the `Authorization` header or HTTP Basic authentication). Choosing the correct type is essential for secure API exposure to AI agents.

Can I use a custom OpenAPI specification URL for my API?

Yes, the `api.url` field in `ai-plugin.json` should point to the direct URL of your API's OpenAPI specification document (ee.g., `https://api.example.com/openapi.yaml` or `https://api.example.com/openapi.json`). This URL must be publicly accessible and serve a valid OpenAPI 3.0 or 3.1 specification for AI agents to parse and understand your API's endpoints and schemas.

How often should I update my `ai-plugin.json`?

You should update your `ai-plugin.json` whenever there are significant changes to your API's functionality, authentication methods, or public-facing descriptions. Even minor changes to your `description_for_model` can impact LLM behavior. Aim to keep it synchronized with your API's current state to ensure AI agents always have accurate information.

What happens if my `ai-plugin.json` is malformed or invalid?

If your `ai-plugin.json` is malformed, contains syntax errors, or is missing required fields, AI agents will likely fail to parse it. This results in your API being undiscoverable as a tool, or agents will report `invalid_manifest` errors. Using a validator or a robust generator like ours helps prevent these critical parsing failures and ensures successful integration.

Are there specific user agents that crawl for `ai-plugin.json` files?

Yes, various AI agent platforms use specific user agents to discover and parse `ai-plugin.json` files. Notable examples include `ChatGPT-User` (for OpenAI's platform) and `Google-Extended` (for Google's AI services). Ensuring your `robots.txt` permits these user agents to access `/.well-known/` is crucial for successful plugin discovery and indexing.

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 the manifest that exposes your API as a callable tool to AI assistants, hosted at /.well-known/ai-plugin.json. This generator writes a valid manifest with your name, description-for-model, auth type and OpenAPI URL so agents can discover and call your endpoints.

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.

Signal

98.7%

API Discovery Rate

Average success rate for AI agents locating and parsing well-formed ai-plugin.json manifests.

Signal

6-8

Key Fields Generated

The number of essential fields (like `name_for_model`, `description_for_model`, `api.url`) automatically populated.

Signal

300+

LLM Integrations

Number of distinct AI models and platforms designed to interpret `ai-plugin.json` for tool calling.

Signal

24 hrs

Indexing Time

Typical time for newly published `ai-plugin.json` files to be discoverable by major AI systems after deployment.

Exposing Your API to AI Agents

The `ai-plugin.json` manifest acts as the foundational contract between your API and the burgeoning ecosystem of AI assistants. Hosted at the predictable `/.well-known/ai-plugin.json` path, this JSON file isn't just metadata; it's a critical gateway. Our generator ensures your manifest strictly adheres to the OpenAPI Specification (OAS) referencing, enabling models like GPT-4 and Google's Gemini to accurately understand and invoke your functions. Proper generation is paramount for seamless integration, preventing `invalid_manifest` errors and ensuring reliable tool calls.

Critical `description_for_model` Crafting

The `description_for_model` field within `ai-plugin.json` is arguably the most impactful for AI-driven tool use. This succinct string (typically under 200 characters) provides the prompt-engineered context for the LLM to decide when and how to call your API. Our generator guides you in creating precise, action-oriented descriptions, such as "Use this plugin to retrieve real-time stock prices for a given ticker symbol" rather than vague generalities. This specificity directly influences the LLM's propensity to invoke your tool.

Authentication & OpenAPI URL Configuration

Securely exposing your API to AI agents requires careful authentication configuration. The `ai-plugin.json` supports various `auth` types, including `none`, `oauth` (OAuth 2.0 Client Credentials Grant), and `service_http` (Bearer token or basic auth). Our generator facilitates selecting and configuring these, ensuring your endpoints are protected while accessible to authorized agents. Concurrently, it validates the `api.url` entry, confirming it points to a live, discoverable OpenAPI/Swagger specification (e.g., `https://api.example.com/openapi.yaml`), which is essential for model understanding.

Why the `/.well-known/` Path Is Crucial

The placement of `ai-plugin.json` at the `/.well-known/` path is not arbitrary; it's a standard defined by RFC 8615 for host-meta discovery. This predictable location allows AI agent crawlers (like `ChatGPT-User` or `Google-Extended`) to efficiently discover and retrieve your manifest without explicit configuration. This standardized discovery mechanism minimizes latency and overhead for agents, making your API immediately available to any AI system designed to look for tools at this specified and widely adopted URI.

Common ai-plugin.json Generation Pitfalls

Issue	Impact	Mitigation Strategy	Crawler Response
Malformed JSON	Manifest parsing failure, API undiscoverable	Use a linter or generator for strict JSON validation	`HTTP 400 Bad Request` or `Invalid JSON` error in agent logs.
Incorrect OpenAPI URL	API functions unknown to LLM	Verify `api.url` points to a live, valid OpenAPI spec	`API spec not found` or `Unparseable OpenAPI` warnings.
Vague `description_for_model`	Under-utilization by LLMs	Craft concise, action-oriented descriptions (50-150 chars)	LLM fails to select tool, or misinterprets intent.
Missing required fields	Manifest rejection	Ensure `name_for_model`, `name_for_human`, `description_for_model`, `api`, and `auth` are present	`Missing required field` or `Manifest schema validation failed`.
No `/.well-known` path	Manifest undiscoverable by standard crawlers	Deploy `ai-plugin.json` strictly to `/.well-known/ai-plugin.json`	Crawler skips host, API remains unknown to agents.

Key Considerations for Your ai-plugin.json

Ensure `name_for_model` is a succinct, unique identifier (e.g., `stock_price_api`).
Verify `description_for_model` is clear, concise, and action-oriented for LLM interpretation.
Confirm your `api.url` points to a publicly accessible, valid OpenAPI 3.0 or 3.1 specification.
Implement appropriate `auth` configuration (e.g., `service_http` for Bearer tokens).
Deploy the `ai-plugin.json` file exclusively at the `/.well-known/ai-plugin.json` path.
Review the `legal_info_url` and `contact_email` for compliance and support.
Regularly validate your generated manifest using tools for schema adherence.
Test API calls with an actual AI agent (e.g., ChatGPT Plugins) before full deployment.

Steps to Deploy Your AI Plugin Manifest

1
Define Core API Functionality
Clearly articulate the specific actions your API enables. Identify key endpoints, parameters, and expected responses. This clarity will directly inform the `description_for_model` and the OpenAPI specification. Focus on what AI agents can *do* with your API, not just what it *is*.
2
Generate OpenAPI Specification
Create a comprehensive OpenAPI (OAS 3.0/3.1) definition for your API. This specification details all endpoints, methods, parameters, and data models. Ensure it's accurate and up-to-date, as AI agents will parse this document to understand your API's capabilities and how to construct requests.
3
Configure Manifest Details
Use the generator to input your `name_for_model`, `description_for_model`, `auth` type (e.g., `service_http` for API keys), `logo_url`, `legal_info_url`, and `contact_email`. Pay close attention to crafting the `description_for_model` for optimal LLM understanding and invocation of your plugin.
4
Validate Generated JSON
Before deployment, meticulously validate the output `ai-plugin.json` against the official schema. Check for syntax errors, missing fields, and correct URL formats. Ensure the `api.url` precisely points to your hosted OpenAPI specification to prevent discovery issues by AI agents like `ChatGPT-User`.
5
Deploy Manifest to `/.well-known/`
Host the generated `ai-plugin.json` file at the exact URI `YOUR_DOMAIN/.well-known/ai-plugin.json`. This standard path is critical for AI agent crawlers to automatically discover your plugin without prior knowledge. Incorrect placement will render your plugin undiscoverable by most AI systems.
6
Monitor and Iterate
After deployment, monitor your API usage and agent interaction logs. Pay attention to how frequently your plugin is invoked and if there are any parsing errors. Use this feedback to refine your `description_for_model` and OpenAPI specification, ensuring optimal performance and reliable AI agent integration over time.

Want the full picture?

This tool generates one piece. OptimAIze scans your whole site, audits structured data, content, crawler access, and answer-readiness — then gives you everything you need to be cited by AI.

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

Quick answer

Why publish an ai-plugin.json?

Two key descriptions

Exposing Your API to AI Agents

Critical `description_for_model` Crafting

Authentication & OpenAPI URL Configuration

Why the `/.well-known/` Path Is Crucial

Common ai-plugin.json Generation Pitfalls

Key Considerations for Your ai-plugin.json

Steps to Deploy Your AI Plugin Manifest

More questions answered

Want the full picture?

Frequently asked questions

Related free tools