AI-Orientated API Documentation

This post builds on our announcement of the Open Agentic Knowledge (OAK) repository. If you're new to the idea, start here.

The difference between a chatbot and an agent is action: chatbots chat but agents act. Agents act via APIs, whether that be a remote REST web service APIs or local STDIO. All agents really need to use an API is good documentation. With good documentation, any frontier LLM can generate python, cURL or bash commands to invoke an API.

When agent tooling is viewed as a knowledge problem, the breadth of API documentation dictates the range of the agents’ capabilities, and the depth of the documentation dictates its reliability.

Overall, quality API documentation can drive both capable agentic planning and reliable tool execution and evaluation. If the agent’s tool spec is vague, ambiguous or incomplete, the agent will call the wrong tool, or call the right tool the wrong way, or misinterpret responses, or fail silently. This leaves us in familiar territory of cool demos that only work in toy cases.

Launching OAK - Open Agentic Knowledge

This is why we believe that good documentation is no longer “nice to have”. Docs are no longer about developer experience; it’s core tool context for agents — and it’s a “need to have”. We call this the knowledge layer.

It was clear to us from day one that the best incarnation of an agentic knowledge layer will live in open-source as a communal solution to a shared challenge, leaving vendor-specific plays far behind. This is why we launched the Open Agentic Knowledge (OAK) repository, embracing widely-adopted open standards like OpenAPI and Arazzo. We are using AI to schematize API and workflow knowledge into these formats, and we are offering it all as a firm foundation for the future of agentic tool use.

"The 𝗢𝗽𝗲𝗻 𝗔𝗴𝗲𝗻𝘁𝗶𝗰 𝗞𝗻𝗼𝘄𝗹𝗲𝗱𝗴𝗲 (𝗢𝗔𝗞) manifesto has 10 sensible principles for how agents and APIs should act together.... It’s also exciting to see their creation of an 𝘼𝙧𝙖𝙯𝙯𝙤 𝙬𝙤𝙧𝙠𝙛𝙡𝙤𝙬𝙨 𝙞𝙣𝙫𝙚𝙣𝙩𝙤𝙧𝙮 with ~1000 workflows listed already! These types of discoverable capabilities (e.g. beyond API endpoints) are exactly what we want to surface towards agents." -Frank Kilcommins, OpenAPI Board Member and Smartbear API evangelist

“The goal of OAK is to leverage AI to create a comprehensive catalog of OpenAPI and Arazzo description documents, which are themselves optimized to power intent-orientated workflows in agents. The repository is now hosting … over 1000 Arazzo descriptions, the largest collection available at the time of writing.” - OpenAPI Initiative Newsletter

Embracing OpenAPI

We wholeheartedly embraced the OpenAPI specifications, but only after careful deliberation. We had spent months working through the details of schematized API knowledge that might be required in different situations by agent code or by an LLM, resulting in a long list of requirements. Creating a good bespoke specification to represent this level of detail would be a multi-year project, which would likely raise valid concerns about vendor lock-in, and cause standards fragmentation (à la XKCD 927).

The OpenAPI specification already satisfies most of these requirements, and has a large community working on extensions that meet many of our additional requirements. It is battle-hardened after 14 years and 3 major versions, and has a thriving tool ecosystem that provides wide interoperability. The next version, OpenAPI 4, will widen support to non-REST APIs and emphasizes agentic use-cases. But it is the Initiative’s Arazzo specification that really won us over. What OpenAPI is to APIs, Arazzo is to agentic tools. It allows a complex multi-vendor workflow composed of API operations and sub-workflows to be succinctly expressed in JSON. It is a perfect fit for representing workflow knowledge that maps cleanly to agent intents and goals. In our view, agent tools should be stored as Arazzo.

We may expand OAK in the future to contain other formats that are well suited to describing the detail and nuance of other kinds of APIs and services that aren’t covered by OpenAPI (perhaps even A2A, AGNTCY or ACP). Our goal is for everything in OAK to be:

• open-standard (for interoperability, scaled adoption and future proofing)
• declarative (for semantic retrieval and planning)
• deterministic (for automated execution)
• indexable (for use in RAG pipelines)
• executable (via open-source tooling or hosted services)

Growing OAK

We are scaling OAK by automatically distilling detailed, machine-readable and declarative API and workflow specifications from the web and from code. It already contains 1500+ APIs, 50K+ API operations and 1000+ workflows (Arazzo provides us with a trusted open standard for declarative workflows, allowing us to collaborate on agentic tools as data instead of code). Everything in OAK can be deterministically executed by agents via the accompanying open-source tools. We will continue to expand this repository, and if you find it's missing anything you can submit an issue, which will be automatically processed by our bots to ingest the new API or to develop the requested workflow.

We are stewarding OAK as the shared knowledge layer that allows agents to reliably select, authenticate, execute, and troubleshoot API calls. By storing this knowledge centrally in widely-adopted open standard declarative formats under the MIT license, we are making it discoverable and reusable by developers, agents, partners and competitors, and we welcome all collaborators.

How to Use OAK

You can use OAK directly from GitHub, or through tooling like:

• oak-runner – an open-source execution engine for API operations and Arazzo workflows
• Jentic – our hosted search/load/execute platform for agents, with managed authentication and permissions
• Build a custom RAG pipeline

You can also use Jentic to just export OAK operations and workflows as OpenAI or Anthropic tool definitions.

Help Us Build the Knowledge Layer

We’re treating this as core infrastructure, and we’re not doing it alone. If you:

• have an API we should index, please submit an issue and our bots will automatically import it
• have a workflow you want to see, please submit an issue and our bots will automatically create it
• have workflows for your own API that you want included, please consider publishing an Arazzo specification
• want to build evals and associated tooling, please join us on Discord and submit a PR
• Want to co-invest in making OAK great (e.g., helping develop API research agents) join us on Discord