| Internet-Draft | API Discovery for AI Agents | October 2025 |
| Hugo | Expires 30 April 2026 | [Page] |
This document describes a method for AI agents to discover, understand, and authenticate to APIs by composing existing Internet standards. It proposes that the combination of api-catalog for discovery, OpenAPI for capability description and schema discovery, and OAuth 2.0 with its associated metadata specifications for authentication and authorization provides a robust, decentralized alternative to bespoke single-purpose protocols.¶
This approach avoids vendor lock-in, reduces complexity by reusing well-understood technologies, and promotes an open and interoperable ecosystem for AI agent interactions with the existing Web.¶
This note is to be removed before publishing as an RFC.¶
Source for this draft and an issue tracker can be found at https://github.com/jbg/agent-api-discovery.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 30 April 2026.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The proliferation of AI agents necessitates a standardized mechanism for them to interact with the vast landscape of existing APIs. These agents require methods to discover available APIs, understand their functionality, and securely authenticate to them on behalf of a user or system.¶
Agent-API interaction faces several challenges:¶
Discovery Fragmentation: No standardized way for agents to discover available APIs across different domains¶
Integration Complexity: Each API requires custom integration code and documentation parsing¶
Authentication Inconsistency: Different APIs use various authentication mechanisms without standardized discovery¶
Vendor Lock-in: Proprietary solutions create dependencies on specific platforms or protocols¶
While solutions like the Model Context Protocol [MCP] have gained popularity, they introduce new protocols and create additional complexity in the ecosystem. These challenges make it difficult for AI agents to dynamically interact with the diverse ecosystem of existing APIs, limiting their effectiveness and creating barriers to interoperability.¶
This document proposes a composable approach that leverages existing Internet standards rather than introducing new protocols. By combining api-catalog [RFC9727], OpenAPI [OAS], and OAuth 2.0 [RFC6749] with its discovery mechanisms [RFC8414], this approach provides a robust, decentralized solution that avoids vendor lock-in and reduces complexity.¶
The core capabilities required by an agent can be broken down into three stages:¶
Discovery: Finding the right API for a given task¶
Description: Understanding the API's endpoints, parameters, and data structures¶
Delegated Authorization: Gaining secure, scoped access to the API on behalf of a user¶
This three-stage approach fully addresses the requirements for AI agent-API interaction using well-established Internet standards.¶
The first stage of agent-API interaction requires the agent to discover which APIs are available for a given task. api-catalog [RFC9727] provides a standardized mechanism for this discovery process.¶
An agent implementing this discovery mechanism SHOULD:¶
Direct Discovery: Query /.well-known/api-catalog or use link relations to discover APIs available on target domains¶
Catalog Processing: Parse the API catalog (in Linkset format [RFC9264]) to extract API endpoints and metadata¶
Capability Matching: Match discovered APIs against the agent's task requirements¶
This approach enables agents to systematically discover APIs across the Web without requiring custom discovery protocols or vendor-specific mechanisms.¶
Once an agent has discovered an API through the catalog mechanism described in Section 1, it needs to understand the API's capabilities, parameters, and data structures. The OpenAPI Specification [OAS] provides a standardized, machine-readable format for this purpose.¶
While OpenAPI documents are typically served at conventional endpoints (such as /openapi.json, /swagger.json, or /api-docs), the api-catalog mechanism described in Section 1 can include direct links to OpenAPI specifications. This creates a seamless flow from discovery to description:¶
Catalog Reference: The api-catalog includes links to OpenAPI documents for each discovered API¶
Direct Access: Agents can fetch OpenAPI documents directly from the URLs provided in the catalog¶
Conventional Discovery: As a fallback, agents MAY attempt to discover OpenAPI documents at common endpoints¶
An agent implementing this description mechanism SHOULD:¶
Fetch OpenAPI Document: Retrieve the OpenAPI specification from the URL provided in the api-catalog¶
Parse Specification: Process the document to extract API metadata¶
Analyze Capabilities: Match API operations against the agent's task requirements¶
Plan Integration: Determine which endpoints and parameters are needed for the task¶
Prepare Requests: Structure API calls according to the OpenAPI schema¶
This standardized approach enables agents to dynamically understand and integrate with APIs without requiring custom integration code or vendor-specific documentation formats.¶
Agents implementing this approach SHOULD handle common failure scenarios:¶
Discovery Failures: If /.well-known/api-catalog is unavailable, agents MAY fall back to conventional OpenAPI discovery endpoints¶
OpenAPI Parsing Errors: Malformed or invalid OpenAPI documents SHOULD be handled gracefully with appropriate error reporting¶
OAuth Flow Failures: Authorization failures SHOULD be communicated clearly to users with guidance on resolution¶
Protocol Errors: Implementations SHOULD handle HTTP error responses and invalid protocol responses appropriately¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This approach relies on the security models of its constituent parts, primarily OAuth 2.0. Implementers MUST adhere to the security best practices outlined in the relevant specifications, including OAuth 2.0 for Native Apps [RFC8252] and OAuth 2.0 Security Best Current Practice [I-D.ietf-oauth-security-topics]. By leveraging these standards, this approach avoids introducing novel security vulnerabilities that a new protocol might create.¶
This document has no IANA actions.¶