Scan Results: https://developers.openai.com/api/docs
ID: 84e72a40-119b-4b36-ad5b-98eba52c1c0a
Legacy Docs (Invisible)
Invisible to AI agents. Severe context noise, non-functional code, or zero discoverable specifications.
Category Breakdown
Detailed Findings
Context Optimization
llms.txt Auto-Discovery
llms-full.txt Consolidated Docs
Markdown Content Negotiation (Accept: text/markdown)
My documentation is returning excessive HTML to AI agents. Implement server-side content negotiation in my app. When a request includes the header 'Accept: text/markdown', return ONLY the technical content as clean Markdown. Strip completely: navigation menus, footers, cookie banners, sidebar links, breadcrumbs, social sharing buttons, interactive widgets, and any HTML not containing technical content. The response should contain only: - Page title as H1 - Section headings as H2/H3 - Body text - Code blocks with language tags - Parameter tables - No HTML tags, no CSS, no scripts
DOM Cleanliness Ratio (6% markdown/HTML)
Reduce layout boilerplate (header, footers, scripts) or use Markdown Content Negotiation to strip DOM noise.
Code Block Execution
This category was analyzed using structural heuristics. Results reflect your documentation's observable patterns.
Terminal Prompt Pollution (No "$" prefixes in copyable code)
Dependency & Import Completeness (AI Check Fallback)
Dynamic Variable Placeholders (AI Check Fallback)
Use structured placeholders like <YOUR_API_KEY> or process.env.
Machine Readability
OpenAPI/Swagger Spec Auto-Discovery
Expose an OpenAPI or Swagger specification at a standard path (e.g. /openapi.json) or link to it using the "Link" HTTP response header with rel="openapi".
JSON-LD Structured Schema (TechArticle / APIReference / Guide)
Embed a <script type="application/ld+json"> block classifying your docs as a TechArticle, Guide, or APIReference, containing semantically enriched metadata.
Agent Tooling & MCP
Model Context Protocol (MCP) Server Integration
Configure and expose an MCP server definition at /.well-known/mcp.json or publish guidelines showing AI agents how to interact with your APIs using MCP tool declarations.
Error Code Diagnostics & Cross-Referencing Index
Provide a comprehensive table or section listing error codes, their causes, and solutions. This lets agents cross-reference error stacks and resolve integration errors automatically.