A presentation at The Future of Software Technologies Conference in in Paris, France by Frank Kilcommins
You May Have OpenAPI, But Is It AI-Ready? Date: Presented by: 11th Dec, 2025 Frank Kilcommins © Jentic - All rights reserved
I’m Frank Kilcommins › Head of Enterprise Architecture @ Jentic › Engineer and Architect ( APIs & Developer Experience) › Governance Board member @ OpenAPI Initiative (OAI) › Co-Author / Maintainer of the Arazzo Specification Connect: @fkilcommins.bsky.social @frank-kilcommins frank@jentic.com © Jentic - All rights reserved
Most APIs were designed for Humans … (most) APIs are intended for developers, but not to be interpreted, reasoned about, or safely executed by AI systems © Jentic - All rights reserved
AI Initiatives Have Mixed Success Aditya Challapally, Chris Pease, Ramesh Raskar, and Pradyumna Chari, “The GenAI Divide: State of AI in Business 2025”, MIT NANDA, July 2025 Alex Singla, Alexander Sukharevsky, Lareina Yee, and Michael Chui, “The state of AI in 2025: Agents, innovation, and transformation”, McKinsey, November 2025 © Jentic - All rights reserved
AI Integration Is the New Moat Tim O’Reilly “AI Integration Is the New Moat”,O’REILLY, Oct 2025 https://www.oreilly.com/radar/integration-is-the-new-moat/ © Jentic - All rights reserved
But We Have OpenAPI! Isn’t That Enough? … you can have valid OpenAPI that is semantically useless to both humans and machines … © Jentic - All rights reserved
Humans Tolerate, Machines Cannot Human Interpretability: ● Vague descriptions ● Inconsistent naming ● Wrong servers ● Missing authentication info ● Missing examples © Jentic - All rights reserved
Humans Tolerate, Machines Cannot Human Interpretability: ● Vague descriptions ● Inconsistent naming ● Wrong servers ● Missing authentications info ● Missing examples Machine Interpretability: © Jentic - All rights reserved
What We Learned Across 1500+ Public APIs See https://github.com/jentic/jentic-public-apis © Jentic - All rights reserved
Findings from 1500+ Public APIs ? ● Invalid or unparsable OpenAPI Docs ● Missing path parameters / broken $ref chains ● Invalid examples ● Examples missing ● Inconsistent naming + unclear verb usage ● Vague or generic descriptions ● No servers or wrong envs ● Auth info missing (outside OpenAPI) ● Stale / outdated OpenAPI Documents © Jentic - All rights reserved
Findings from 1500+ Public APIs ? Invalid OpenAPI Security vulnerabilities Missing semantics Missing path ● No servers defined ● Examples missing parameters ● Wrong environments ● Inconsistent naming ● broken $ref chains ● Auth info missing ● Unclear verb usage ● Invalid examples ● Stale or outdated ● Vague or generic ● OpenAPI Documents descriptions © Jentic - All rights reserved
Typical Example Agent interpretation: ● It might create a user ● It might replace a user ● It might partially update a user ● It might patch only some fields © Jentic - All rights reserved
What AI Systems Actually Need Agents need APIs to be: ● Interpretable: Intent must be explicit ● Composable: Clear inputs / outputs ● Safe: Auth & safety signals machine readable ● Discoverable: able to find and classify API ● Predictable: idempotency, stable responses ● Resilient: Clear signals for success and failure © Jentic - All rights reserved
You Can’t Improve What You Can’t Measure AI-readiness starts with understanding your current API landscape © Jentic - All rights reserved
API AI-Readiness Framework Evaluates APIs across six human & AI-readiness dimensions: ● Foundational Compliance ● Developer Experience (including tooling compatibility) ● Agent Experience (AI-Readiness) ● Agent Usability ● Security ● AI Discoverability © Jentic - All rights reserved
AI-Readiness Scorecard See https://jentic.com/scorecard © Jentic - All rights reserved
Foundational Compliance Evaluates if an API is structurally valid, standards-compliance, and parseable by tooling. The following signals comprise the dimension: Signal Description Normalisation Spec validity Checks whether the API parses as a valid OpenAPI binary Resolution Completeness What proportion of $ref references successfully resolve coverage Lint Results Aggregated quality score from linter diagnostics, weighted by severity. Inverse weighted categorical Structural Integrity Measures whether the API’s underlying data model is coherent enough for automated reasoning (semantic or logical defects that impact reliable interpretation) Logarithmic dampening © Jentic - All rights reserved
Foundational Compliance Evaluates if an API is structurally valid, standards-compliance, and parseable by tooling. The following signals comprise the dimension: Signal Description Normalisation Spec validity Checks whether the API parses as a valid OpenAPI binary Resolution Completeness What proportion of $ref references successfully resolve coverage Linting Results Aggregated quality score from linter diagnostics, weighted by severity. Inverse weighted categorical Structural Integrity Measures whether the API’s underlying data model is coherent enough for automated reasoning (semantic or logical defects that impact reliable interpretation) Logarithmic dampening © Jentic - All rights reserved
Foundational Compliance Evaluates if an API is structurally valid, standards-compliance, and parseable by tooling. The following signals comprise the dimension: Signal Description Normalisation Spec validity Checks whether the API parses as a valid OpenAPI binary Resolution Completeness What proportion of $ref references successfully resolve coverage Linting Results Aggregated quality score from linter diagnostics, weighted by severity. Inverse weighted categorical Structural Integrity Measures whether the API’s underlying data model is coherent enough for automated reasoning (semantic or logical defects that impact reliable interpretation) Logarithmic dampening © Jentic - All rights reserved
Developer Experience Assesses clarity, documentation quality, example coverage, and compatibility with developer tooling. The following signals comprise the dimension: Signal Description Normalisation Example Density Measures coverage of examples across all eligible specification locations coverage Example Validity Checks all examples for Schema Conformance (JSON + XML) coverage Doc Clarity Quantifies linguistic clarity of summaries and descriptions. Basically, how easy is it to understand the intent, and the complexity of verbiage. Min-max inverted Response Coverage Presence of meaningful success and error responses across full surface area coverage © Jentic - All rights reserved
Developer Experience Assesses clarity, documentation quality, example coverage, and compatibility with developer tooling. The following signals comprise the dimension: Signal Description Normalisation Example Density Measures coverage of examples across all eligible specification locations coverage Example Validity Checks all examples for Schema Conformance (JSON + XML) coverage Doc Clarity Quantifies linguistic clarity of summaries and descriptions. Basically, how easy is it to understand the intent, and the complexity of verbiage. Min-max inverted Response Coverage Presence of meaningful success and error responses across full surface area coverage © Jentic - All rights reserved
AI-Readiness & Agent Experience Evaluates where an API gives enough context for AI systems to understand its intent, constraints, and expected behaviours. The following signals comprise the dimension: Signal Description Normalisation Summary Coverage Measures presence of concise summaries across eligible locations coverage Description Coverage Measures presence of concise descriptions across eligible locations coverage Type Specificity Rewards APIs that model values semantically, not just as loosely typed strings weighted categorical Error Standardisation Favour structured error formats (RFC 9457/7807) coverage Operation Identifier Quality evaluate presence and distinctiveness of operationId values composite Policy Presence Promote inclusion of SLA/rate-limit/policy metadata coverage AI Semantic Surface Bonus uplift for AI-oriented metadata bonus multiplier © Jentic - All rights reserved
Agent Usability Assesses how efficiently agents can navigate, combine, and execute API operations. Measures orchestration safety and agent ergonomics. The following signals comprise the dimension: Signal Description Normalisation Complexity Comfort Measures document size, endpoint density, and schema complexity, penalised using a logistic curve logistic shaping Distinctiveness Quantifies semantic separation between operations inverse semantic similarity Navigation (pagination, hypermedia) Evaluates pagination and hypermedia affordances (HATEOAS, JSON:API, HAL) composite Intent Legibility Evaluates verb-object semantic clarity similarity (LLM assisted) Safety Evaluates idempotency & sensitive operation protection heuristic penalty Tool Calling Alignment Represents alignment with LLM tool-calling expectations coverage © Jentic - All rights reserved
Security Assesses if your API protects data, enforces access controls, and follows secure-by-design practices. The following signals comprise the dimension: Signal Description Normalisation Auth Coverage Evaluates whether authentication is correctly applied to sensitive or modifying operations, using intent-aware heuristics heuristic penalty Auth Strength Measures robustness and correctness of authentication mechanisms declared by the API using normative scores based on IANA auth-schemes, OAuth2,, OIDC, API Key placement, and mutual TLS weighted categorical Transport Security Requires HTTPS for externally exposed hosts binary Secret Hygiene Detect and penalise hardcoded credentials binary Sensitive Handling Evaluates the protection of PII/sensitive fields coverage OWASP Posture Reflect severity-weighted risk findings severity weighted © Jentic - All rights reserved
Security Assesses if your API protects data, enforces access controls, and follows secure-by-design practices. The following signals comprise the dimension: Signal Description Normalisation Auth Coverage Evaluates whether authentication is correctly applied to sensitive or modifying operations, using intent-aware heuristics heuristic penalty Auth Strength Measures robustness and correctness of authentication mechanisms declared by the API using normative scores based on IANA auth-schemes, OAuth2,, OIDC, API Key placement, and mutual TLS weighted categorical Transport Security Requires HTTPS for externally exposed hosts binary Secret Hygiene Detect and penalise hardcoded credentials binary Sensitive Handling Evaluates the protection of PII/sensitive fields coverage OWASP Posture Reflect severity-weighted risk findings severity weighted © Jentic - All rights reserved
AI Discoverability Evaluates how easily AI systems can locate, classify, and route to the API across registries, workflows, and knowledge bases. The following signals comprise the dimension: Signal Description Normalisation Descriptive Richness Evaluates the semantic value of textual descriptions within an API description. coverage Intent Phrasing Evaluates verb-object clarity of summaries and descriptions (Similar to Intent_legibility) semantic similarity (LLM assisted) Workflow Context Evaluates indicators to workflow specifics including Arazzo/MCP/workflow references. Also analyses existence of callbacks etc. coverage Registry Signals Detects metadata related to API gateways, llms.txt, APIs.json, MCP registries, externalDocs links to Dev portals. coverage Domain Tagging Detect domain/taxonomy classification through the use of tags coverage © Jentic - All rights reserved
Landscape Readiness Overview Coming soon at: https://jentic.com/leaderboard © Jentic - All rights reserved
Readable summaries & descriptions Semantically rich schemas Full use of “Examples” Correct HTTP Methods Use RFC 9457 Problem Details of Errors Making OpenAPI Descriptions AI-Ready Appropriate HTTP status code usage Defined Servers & Environments Prompt hints and AI-metadata extensions Codify Intent-based use cases and workflows Codified security & SLA details © Jentic - All rights reserved
Entering the “Context Stage” of APIs “Endpoints != Use-cases. Think about the workflows” - Adam DuVander © Jentic - All rights reserved
The Future: Machine-First API Design OpenAPI 3.3: Arazzo 2.0: Encourage formal semantics ● gRPC, MCP, GraphQL step support (JSON-LD perhaps) ● Human-in-loop support ● Improve OAuth / OIDC support ● Agent-in-loop support ● Improved Header support ● Transformer / function support ● Loops ● © Jentic - All rights reserved
Get your AI-Readiness score: jentic.com/scorecard Thank you! Connect: @fkilcommins.bsky.social @frank-kilcommins frank@jentic.com © Jentic - All rights reserved
I have worked with and reviewed thousands of APIs across startups, enterprises, and global platforms. Almost all shipped an OpenAPI Description. Yet through the lens of AI systems and intelligent agents, most failed a simple test. They were designed for humans (often badly), not machines.
In this session I will share what I have learned from helping organisations make their APIs truly AI-ready, breaking down the six dimensions that determine whether an API can be understood, reasoned over, discovered, and safely executed by intelligent systems. These include foundational compliance, developer experience, semantic clarity, agent usability, security, and AI discoverability.
Using the Jentic API Scoring Framework as a visual guide, I will show how to assess AI-readiness, where most teams stumble, and the simple changes that dramatically improve both human and machine understanding.
for free. You
can too.