Pooja Vijay Kumar and Aman Talwar (Autodesk): Specs Are Docs Now: Designing OpenAPI for Agentic Interfaces

This talk was presented at the AI The Docs 2025 online conference. We are thrilled to share the recording and the summary with you. 

Visit the talk summary page to see all of the presentations from the conference.

presentation

Pooja Vijay Kumar (Content Design Leadership at Autodesk) and Aman Talwar (Content Design Manager at Autodesk)

Summary 

What is the fundamental flaw with most current OpenAPI specifications, and why is this problematic for AI systems? 

In their talk, Pooja Vijay Kumar (Content Design Leadership at Autodesk) and Aman Talwar (Content Design Manager at Autodesk India) describe the problem: most OpenAPI specs are not written, they are generated which leads to semantically hollow specs.

Autogenerated OpenAPI specs are technically valid but lacking meaning. They include vague descriptions, missing examples, and no constraints. Historically, this was fine because specs were for pipelines, not people. But now LLMs, agents, and tools “read” these specs, and shallow specs lead to shallow AI outputs: brittle prompts, flaky chaining, and unreliable co-pilots. 

The solution: semantically expressive specs 

AI thrives on structure, specificity, and examples. Well-formed specs become a frontline UX layer for AI. Key elements include: 

• Clear, precise descriptions
• Defined object/parameter types with constraints
• Explicit examples (not placeholders)
• Enums as “AI handrails”
• Thoughtful error responses
• Explicit definitions of valid/invalid values 

This shifts models from probabilistic guessing (hallucination risk) to predictable reasoning. 

Fixing legacy specs 

Specs “age like bananas and not like wine”: autogenerated, barebones, inconsistent. To uplift them: 

• Organize information clearly for LLM parsing
• Apply linters and standards at write time
• Use analytics and support feedback to catch drifts and confusions 

OpenAPI as UX blueprint + AI readiness 

Specs should be treated as UX blueprints that shape both human and AI experience. Autodesk demoed an AI readiness monitor that scored specs on semantic health. A spec rated 60% could be auto-fixed to 100%, showing how even “valid” specs may miss crucial AI-facing components. 

New workflows and roles 

As specs become frontline interfaces, roles evolve: 

• API Designers: interface architects, ensuring accuracy and completeness
• Technical Writers: AI workflow managers, shaping prompts and narrative around specs
• Product Leaders: strategic investors in AI-ready documentation 

Key takeaway: The future of API documentation isn’t static pages but architecting smarter interactions. Specs must be semantically rich, human-guided, and AI-ready to support reliable agent behavior.