Skip to content

AI Agent API Discovery

API Platform's Developer Portal has built-in support for AI agent discoverability. Every published API is automatically exposed through a set of machine readable endpoints that AI agents, LLM powered assistants, and agentic frameworks can use to discover, understand, and invoke APIs without human assistance.

This page explains how those endpoints work and how agents navigate the portal.

llms.txt: The Entry Point for Agents

The portal dynamically generates an llms.txt file — a plain-text Markdown index designed as the entry point for AI agents. It provides a structured overview of everything the portal exposes for AI consumption.

Endpoint:

GET /{orgName}/views/{viewName}/llms.txt

What it contains:

  • The portal's name, description, and any LLM Instructions configured by the portal admin
  • A list of all agent visible APIs, each with its name, description, and a link to its Markdown documentation
  • A list of all published, agent visible API Workflows

An agent or agentic framework that starts at llms.txt immediately understands the scope of available APIs and workflows without crawling the entire portal. This makes it the standard starting point for LLM native API consumption.

Tip

Portal admins can enrich llms.txt with high-level guidance for agents such as how APIs are organized, common authentication patterns, and recommended workflows using LLM Instructions.

Machine Readable API Endpoints

Beyond llms.txt, the portal exposes all content as clean Markdown and raw specification files. These endpoints require no authentication, no JavaScript rendering, and no browser. Therefore, agents can fetch them reliably as plain text.

API Catalog and Per API Documentation

Endpoint Description
/{orgName}/views/{viewName}/apis.md All agent-visible APIs as a single Markdown document
/{orgName}/views/{viewName}/api/{apiHandle}.md Full documentation for a specific API in Markdown, including description, documents, and a link to the specification

API Specifications

Endpoint Description
/{orgName}/views/{viewName}/api/{apiHandle}/docs/specification.json OpenAPI or AsyncAPI specification (JSON)
/{orgName}/views/{viewName}/api/{apiHandle}/docs/specification.graphql GraphQL schema
/{orgName}/views/{viewName}/api/{apiHandle}/docs/specification.xml SOAP specification (WSDL/XML)

MCP Server Catalog

Endpoint Description
/{orgName}/views/{viewName}/mcps MCP server catalog page
/{orgName}/views/{viewName}/mcp/{apiHandle}.md Full documentation for a specific MCP server in Markdown
/{orgName}/views/{viewName}/mcp/{apiHandle}/docs/specification.json MCP server specification

API Workflows

Endpoint Description
/{orgName}/views/{viewName}/api-workflows.md All published, agent-visible workflows as a single Markdown document
/{orgName}/views/{viewName}/api-workflows/{handle}/arazzo.json Machine readable Arazzo specification for a specific workflow

How Agents Navigate the Portal

A typical agent discovery flow looks like this:

  1. Start at llms.txt — the agent fetches the portal's llms.txt to get an overview of available APIs and workflows.
  2. Browse the API catalog — if the agent needs more detail, it fetches apis.md to read descriptions of all APIs at once.
  3. Retrieve per API documentation — once the agent identifies a relevant API, it fetches /{orgName}/views/{viewName}/api/{apiHandle}.md for full documentation.
  4. Fetch the specification — the agent retrieves the OpenAPI, GraphQL, or AsyncAPI specification for the precise endpoint and parameter details needed to make a call.
  5. Follow a workflow — if a published workflow matches the task, the agent retrieves the Arazzo specification and agent prompt to follow a vetted, step-by-step call sequence rather than reasoning from scratch.

Visibility Controls

By default, all published APIs and MCP servers are agent-visible. API publishers can hide specific APIs from agent-facing surfaces without affecting their visibility to human users in the portal. Portal admins can also disable AI discoverability across the entire portal.

For details on how visibility is controlled, see Make an API AI-Ready.