All articles

Why AI Agents Need Standard Observability

There’s no way to know what an AI agent is doing. Not in the sense of knowing exactly the steps the agent took to complete a task, or to reach a failing state. There’s no backtrace, no information about why something didn’t work. The only thing you get is a generic error message. And that doesn’t help if you’re trying to debug and improve your system. Fortunately, there’s a solution. It involves using OpenTelemetry (OTel) to record traces, metrics, and logs of your agent. This article is brought to you with the help of our supporter, n8n. n8n is the fastest way to plug AI into your own data. Build autonomous, multi-step agents, using any model, including self-hosted. Use over 400 integrations to build powerful AI-native workflows. Try n8n now! Traditional software doesn’t change while it’s running. Software written once and then deployed does what it was designed to do until you replace it. By contrast, you can’t guarantee that an AI agent will do the same thing in the same way twice. AI agents can make decisions based on live data, affecting the tools they choose to use. So, if a tool request returns something unexpected, it will negatively affect all subsequent choices. One, or many, of those following requests will certainly fail. But it’s not that failure that matters the most. What you want to know is which choice led to that failed request, and what data informed the decision. Traditional monitoring won’t give you that information. You can have all the health checks green and still see the AI agents tripping while using your API or MCP. Standard observability solutions won’t be of much help here, either. They’re focused on errors and aren’t good at detecting patterns, which is what you need to look for. Not knowing what’s making AI agents fail has a real cost, too. API owners will see traffic spikes whenever AI agents enter endless retry loops. And end users will also see token usage rise as a result of all the increased chatter. On top of that, not knowing why things are failing keeps your SRE team busy and unavailable to work on other difficulties. The solution, until now, has been to go through chat transcripts and tool request logs, trying to find a cause for the bad choice that led to a failure. Some teams have even been trying to repurpose traditional APM tools. As the frustration grew, vendor-specific observability products like LangSmith, Arize AI, and Helicone entered the market. They can help solve the problem, but they’re not the long-term solution we’re looking for. Each one of them uses its own proprietary data format. That’s why. Instead, what we need is to follow the standard observability pattern of traces, metrics, and logs. This is what frameworks like OTel follow, so it’s a proven way of working. How does it work, then? With traces, you can map an end-to-end chain of tool executions in chronological order. You get to see every request and its response in sequence, rather than a list of isolated events. With metrics, you can aggregate what happens in individual executions and obtain long-term trends. You can track token consumption, latency between workflow steps, cost per task, and the rate of failure across thousands of executions over time. Finally, with logs, you can inspect the exact payload at a specific point in time. These three things, together, make a powerful solution to understand the reason behind the failures. Why Standard Observability Matters Relying on custom SDKs ties your telemetry directly to a single platform and its dashboard format. The moment you want to switch tools or analyze data elsewhere, you end up rewriting your instrumentation from scratch. Standard observability avoids that lock-in by separating how you collect telemetry from where you store and visualize it. Making the solution work isn’t necessarily complicated. But it needs a working hierarchical span tree set up at execution start. Wait, a span tree? What does that even mean? A span, in OTel, is the single unit of work. It represents a tool call, for example, with a start time, duration, any attached attributes, and a status. A span lets you know when the call happened, how long it took, what it was about, and if there was an error. When an AI agent starts a task, OTel opens a root span that covers the entire execution lifecycle. At that point, OTel generates a trace ID that will be used across all subsequent actions. This is how those actions, also known as child spans, are attached to the root. And that’s why this span representation is called a tree. With this approach, you can identify a failure, understand all steps that led to it, and what the initial action was. Here’s an example of what a span tree looks like: trace_id: 8f2c1e... (root: agent.execution) ├── span: llm.call (model: gpt-4o, status: ok, 310ms) ├── span: tool.call (name: validate_email_address, status: ok, 95ms) ├── span: tool.call (name: add_subscriber_to_list, status: ok, 240ms) ├── span: llm.call (model: gpt-4o, status: ok, 620ms) └── span: tool.call (name: send_confirmation_email, status: error [502 Bad Gateway], 50ms) It’s important that the information you’re capturing follows open standards and isn’t attached to any proprietary format or convention. So, following OTel’s Generative AI Semantic Conventions is mandatory. They “establish standardized guidelines for how telemetry data is structured and collected across platforms, defining inputs, outputs, and operational details.”1 GenAI spans, in particular, “represent logical operations as observed by the caller.”2 The advantages of following these conventions are that you don’t have to reinvent everything yourself and, at the same time, you can use any available open-source compatible tool. In August 2026, instrumentation tooling was available for Agno, Anthropic, LangChain, OpenAI, Qwen, smolagents, and Google. Instrumentation for Claude Agent, CrewAI, and others was still being developed. If your code is using one of these agents’ SDKs, all you have to do is configure the appropriate instrumentation. The alternative, in case you don’t want to get your hands dirty, is to use a commercial solution. If you’re using a modern workflow service that talks to AI agents, check its feature list. As the technology matures, more platforms are offering OTel-compatible traces out of the box. Keep in mind that OTel GenAI Semantic Conventions aren’t fully mature yet, so I’d expect substantial changes. While commercial solutions can protect you against those changes, they can’t guarantee everything will always work between SDKs, platforms, and AI agents. It all depends on how quickly each solution adapts to changes. One SDK might comply with the latest version of the conventions, and the tracing solution you’re using might fall behind, creating potential incompatibilities. On top of that, if you use an open-source solution, you also have to think about the overhead of maintaining the telemetry backend yourself. But even if everything is working, capturing everything that happens with an AI agent is expensive. All those system prompts, LLM responses, and frequent tool responses consume a lot of storage and bandwidth. So, think twice before you blindly follow the advice of one of the many available tutorials. Most of them are pure marketing material aimed at selling you a specific solution. Always be skeptical of what you read (this article included). Being skeptical means you should evaluate all options before deciding. You can continue to follow ad-hoc debugging techniques that you know still work, or you can invest now in building proper observability for your AI agent. With observability, you’ll be able to understand what happened during an agent’s execution of a task. This is just the beginning. The next step would be to evaluate the quality of the execution and how well tasks are completed. But to get there, you need to start with observability so you can analyze execution traces. Yes, putting all this together requires time and effort. But using the same manual tools also has its cost when serious production failures happen. Whether you need full OpenTelemetry tracing today depends on how critical your AI agent is to your operations. The decision is all yours to make. Thanks for reading The API Changelog! Please consider subscribing to receive new posts and support our work. Subscribe now Not convinced yet? Get to know why we’re considered “the most important API newsletter out there.” 1 OpenTelemetry for Generative AI, Robbins et al, December 2024 2 Semantic conventions for generative client AI spans, GitHub repository, August 2026

Aug 28, 20261 likes

Can MCP Servers Finally Get Their Own OpenAPI?

You don't know what MCP servers do. Not until you connect and run the tools/list method. And MCP servers are everywhere now. Every AI product wants one, every API team is being asked to build one, and the ecosystem is moving faster than you can keep up with. New servers show up every day, some official, some hacked together over a weekend, all exposing tools, resources, and prompts that AI agents are supposed to know how to use. And there's no way to know what they do until you connect. There's no document you can just open and read, no machine-readable reference you can point your tools at, nothing you can check before deciding whether to use an MCP server. Annoying, right? Stay with me to see how this can change. This article is brought to you with the help of our supporter, Scalar. Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth. Try Scalar for free! Something as simple as an OpenAPI document can give you knowledge about anything related to an API: operations, parameters, authorization, even support contact in case you need it. You don't have to connect to the API to know what it does. Think, for a second, how strange that would be. But that's exactly what happens with MCP. The protocol only tells you how to ask a server what it does while it's running. There's no way to know what an MCP server offers before you turn it on. This isn't just inconvenient. It also makes a few things difficult. Let's start with documentation. Someone has to write it, and today that means running the server, poking at it, and writing down what they find by hand. Nobody can design a server on paper before building it, because there's nothing to design against. Every software that wants to inspect a server has to build its own way of connecting and asking, because there's no shared file to read instead. And worst of all, there's no way to check that a server actually does what it claims. You just have to run it and trust it. So, what have people done about it? They’ve been dealing with this problem in different ways for a while now. Some teams have been writing internal docs by hand. Some wrap their MCP servers with OpenAPI-style descriptions attached on the side. Some write one-off scripts that connect to a server, dump whatever it returns, and pass that around as documentation. A few just keep a spreadsheet of every tool and resource a server exposes, updated by hand. None of these are standardized, of course. That’s why they don’t work well across tools. And adoption is limited, making them almost impossible to survive when a team changes. Every one of these workarounds solves the same problem in a slightly different way. What’s missing isn’t more effort. It’s a format everyone can agree on. A real standard. Is there a real fix, though? One project is trying: mcpdesc. Their pitch is simple: OpenAPI, but for MCP. Instead of connecting to a server to find out what it does, you write (or generate) a static file that says exactly what the MCP server offers: its tools, resources, prompts, transports, and security. You get all the information in one place, in YAML or JSON. Here’s what a minimal mcpdesc document looks like: mcpdesc: 0.7.0 info: name: newsletter-subscriptions-server version: 0.1.0 transports: - type: stdio command: newsletter-subscriptions args: [serve] tools: - name: subscribe_to_newsletter description: Subscribe an email address to a newsletter inputSchema: type: object properties: email: type: string description: Email address to subscribe required: [email] outputSchema: type: object properties: subscription_id: type: string description: Unique identifier for the new subscription status: type: string enum: [confirmed, pending] description: Whether the subscription is active or awaiting email confirmation required: [subscription_id, status] Here's what this description looks like when rendered by the Live MCP Description Editor. Pretty neat! That’s it. You don’t need a running MCP server just to know what this thing does. And if you already have a server running, you don’t even have to write the description by hand (a CLI called mcpcontract can connect to a live server and dump a full mcpdesc document). Once you have the file, things get easier: you can generate real documentation straight from it instead of writing it by hand, lint it, validate it, and diff two versions to understand what changed. You can check it into your CI/CD pipeline like any other artifact, compare what a server claims against what it actually does, and design a server on paper first, or mock it with mcpmock, and only then write the code. You can, essentially, do anything you can do with an OpenAPI document. But for an MCP server. So what does it actually take you to get there? Right now, mcpdesc is a young, single-vendor project. The spec is version 0.7.0 and marked Draft. The only credited maintainer is Stève Sfartz, a Principal Architect at Cisco, and every tool that reads or writes the format (mcpcontract, mcpmock, the editor) comes from the same place: Cisco’s open source org. It was announced about a month ago. Nobody outside that project has adopted it yet. Also, something to take into account is that MCP’s own Server Cards proposal, SEP-2127, looked at describing a server’s tools and prompts and explicitly set it aside for now. That means they could still absorb it at a later stage, making mcpdesc redundant if both standards ever compete. Even the ability to inspect a running MCP server and generate a description has a real limit. Sfartz told me that “live discovery using the dump command is not sufficient for MCP servers that expose different tools based on user permissions,” so for those servers you’re better off generating the description straight from the code than trusting a live dump (check my full interview with Sfartz further down if you want all the details). If you start using it today, you’re adding one more file to keep in sync with reality, on a spec that could still change shape, built by a maintainer who himself says mcpdesc “is not necessarily” the format that ends up standardized. Especially if the folks at Anthropic and the other MCP maintainers decide to build it into the protocol themselves. Why so much negativity? I’m just being realistic so you know what you’re getting. Here’s the actual choice. You can keep living without a description, which costs you nothing today but leaves you unable to write real docs, test conformance, or design servers ahead of time. Or you can start writing mcpdesc files now, knowing it’s early and it’s a single company’s bet. I’d try it. The problem is real, and writing mcpdesc documents sounds easy. But I wouldn’t use it in production yet. There’s still too much ambiguity at this point. But you’re not me, so take your time and make your choice. Stève Sfartz, Principal Architect at Cisco, during a call we had recently. Here’s the full interview with Stève Sfartz from Cisco. Some parts have been edited for improved readability. Bruno Pedro: Why do we need a separate document to describe what an MCP server does, when the protocol already lets you inspect it live? Stève Sfartz: We identified the need for a static document while publishing documentation for the very first MCP servers that came in at DevNet. This blog post from August 4, 2026 provides some details: Beyond the Protocol: Applying API Engineering Practices to MCP Servers. In summary, these are the questions we needed to have answers for to publish documentation, questions that the MCP protocol alone could not address: How do we document MCP servers consistently? How do we review them before publication? How do we compare one release with the next? How do we detect major changes across releases? And beyond, I am responsible for quality and consistency across the whole portfolio. I needed these questions answered: How do we keep engineering teams, documentation teams, and developer-facing portals aligned? (governance) How do we ensure consistency within a product and across products? (compliance) That is why we started creating a description document for MCP servers. BP: mcpdesc is a Cisco project with you as its single credited maintainer, right? SF: The initiative started at DevNet, where I am the lead maintainer. The tooling is used internally at Cisco for publishing and internal workflows. The need for such a format was identified in the spring of 2025. I could not identify any similar initiative in the community, so, as the lead architect, I built the first version of mcpdesc. That happened between July and August 2025 for DevNet publishing purposes. After that, I built the mcpdesc tooling between September and December 2025, first focusing on the mcpcontract dump capability, and then the mcpcontract changelog. Other tools came from internal teams building MCP servers as needs emerged. For instance, mcpmock, one of those tools, is interesting to drive a design-first approach to MCP servers. And mcptest has received very little feedback so far. The MCP Server Card specifications, SEP-2127, originally targeted documenting capabilities (tools, prompts, resources). Our goal was to switch the mcpcontract tool to use the server card format once standardized. But SEP-2127 finally focused on discovery only and omitted capabilities, i.e., primitives, as mentioned in the draft, leaving this aspect to future work. That’s when we decided to publish the MCP description (mcpdesc) externally, and contribute with our internal toolset to the community. I then created mcpdesc.org to start the conversation and promote the need for a standardized format. However, mcpdesc is not necessarily that format. We will be evolving it as needs arise, while engaging with the MCP specifications maintainers to create an official standard. BP: Why should anyone outside Cisco trust it enough to build on it? SF: Well, if a format such as the MCP description existed, we would have built on it rather than created a new one. We shipped the toolset at Cisco Open with an Apache license, and are now working on v0.8 of the format to support MCP 2026-07-28. We also created mcpdesc.org as an open initiative to evolve the format as needed. I’d encourage everyone to test the toolset and the mcpdesc format with their own MCP servers and contribute to improve and extend the toolset. The future will say if there is enough traction for a standardized description format. Best case, it’s a yes, and the mcpdesc format (or a pretty similar one) is standardized. Worst case, it’s a no, and the mcpdesc format will still exist for individuals that see benefits in using it. BP: If someone wants to try mcpdesc on a real server right now, what’s the first thing they should do, and where are they likely to get stuck? SF: The mcpdesc.org portal is very recent and being actively worked on. I’d suggest testing the format using the live editor. There are specification examples included, and anyone familiar with OpenAPI and its tool ecosystem should ramp up in minutes, if not seconds, as the format and tools are inspired by OpenAPI. Indeed, mcpdesc targets the exact same needs as OpenAPI does for REST APIs, but applied to MCP servers. There is no rocket science here, simply applying API engineering best practices to MCP. MCP is very different from a REST or Web API. The protocol is very rich, which offers many benefits and features related to dynamic discovery and agent interactions, and the Anthropic team and MCP maintainers are doing a great job. The tools around MCP are still being built, and it’s time for everyone to contribute to the success of MCP. I hope mcpdesc (or a similar format) will help the tooling ecosystem by offering a standardized way to describe MCP servers so that all engineering quality, compliance, and governance activities can be organized based on a standardized format. After trying the mcpdesc format live in the editor, I’d recommend creating a dump of an existing server using the mcpcontract CLI with the dump command. Dumps are pretty straightforward to create for stdio and HTTP servers. For servers using OAuth, there can be some challenges with some OAuth implementations based on the discovery sequences. Using the --verbose mode should help you diagnose any issue. One note: live discovery using the dump command is not sufficient for MCP servers that expose different tools based on user permissions. In such situations, generating an MCP description document from the actual code (using comments or annotations) would be a better approach. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Aug 21, 20262 likes

Why AI Agents Don't Need Your Full API

The easiest thing you can do is make your entire API available to AI agents. However, "by presenting the LLM with fewer, more relevant tools, we reduce confusion, allowing the model to focus better and achieve higher accuracy"1. You see, different API operations can have similar parameters, descriptions, and, from the outside, look alike. When the LLM selects which tool to use, it compares semantic descriptions. If those descriptions are similar between tools, AI agents won't know which ones to use. In addition to that, every exposed API operation requires injecting its full JSON schema (parameters, types, descriptions, and required fields) into the model's prompt. All that leads to an overload of the AI context window, generating high latency and leaving practically no room for whatever you want your user prompt to be. If exposing more operations is bad, then why are so many doing it? Is there a better alternative? Of course. Keep reading to know more. This article is brought to you with the help of our supporter, Naftiko. Naftiko is a platform that helps organizations manage their technical assets as business capabilities. It provides a central space where teams can define and discover what their services can actually do. By moving the focus away from raw API operations, Naftiko helps engineering and product teams work better together. The more you share, the less accurate the results will be. That’s what happens when you overload an LLM’s context window. To understand why, let’s see how LLMs interpret an API and how that interpretation leads to a decision of which tools to use. To begin with, the ability to interpret an API isn’t something that LLMs can do natively. “Tool use,” or “function calling,” depending on who you ask, is the name of the technique. AI agents control the LLM by directing it to generate a structured query that matches the best API operation schema. This way, instead of trying to come up with a direct answer to a question (the user prompt), LLMs generate an API request that the agent will then make to obtain an answer. So, how can the LLM decide which operation is the best, and then generate an API request with the right parameters? It needs to load the machine-readable definition of all the existing operations, and then parse some of its features. It first extracts the names of all the exposed operations. Then, it calculates the semantic meaning of each operation description. After this step, it goes through the input and output definitions and stores them along with each operation name and semantic meaning. You can see that the more operations you expose, the more information the LLM will need to store, right? But the major problem lies ahead, in the step the LLM takes to decide which operation to use. It has to go through all the available operations and find the one that best matches the user prompt. Having a lot of operations easily leads to loss of accuracy in the decision-making process, which eventually leads to making requests to the wrong API operations. Even worse, if the user prompt leads to an orchestration with multiple steps, erring in deciding which operation to use on each step leads to a failed workflow execution. I imagine you’ve been in this situation more than once by now, right? Fortunately, there’s a solution, and it doesn’t require a lot of heavy lifting, just the right combination of tools. If the problem is that there are too many exposed API operations, then the solution must be to reduce them. And one way to do that is to, somehow, combine multiple operations into individual domain-specific capabilities. Instead of teaching AI agents how to navigate between API operations, you expose entire workflows behind a single request. The trick is to find the workflows that make the most sense and expose those only. And expose them in a way that the AI agent fully understands. The best option right now is to expose them as MCP tools following the best practices in naming, documentation, parameters, output, and error definitions. So, how do you expose a group of API operations in a way that AI agents can easily consume and execute? Before exposing them, you have to design them. Think about them as capabilities that end users will need. However, end users won’t execute them directly. Instead, they’ll prompt their AI agents, who, in turn, will be the ones calling those workflow operations. Craft the best possible interface you want those AI agents to have access to and define it using a well-known machine-readable format for easy evolution and maintenance. My choice here is to use OpenAPI or something similar, easy to type and understand. Then, behind each one of those composite operations, you define a workflow that implements the capability you’re exposing. You can do that with any open-source or commercial workflow orchestration tool that exposes an endpoint to trigger executions. Arazzo, for instance, is a great way to define how a workflow behaves in a machine-readable way. So, now you have an OpenAPI definition exposing one or several capabilities, where each one points to a workflow. Every time someone calls one of those composite operations, a workflow is triggered, and the result is returned to the caller. With this approach, you can now easily expose the composite operations as MCP tools using open-source solutions such as reShapr or the Infobip OpenAPI MCP framework. If you want a more integrated path, Naftiko makes it easy to wire these workflow definitions directly into agent-ready tools. Of course, there’s a cost associated with exposing those capabilities. First, you’ll have to invest time up front to analyze those workflows and write all those machine-readable capability definitions. Then you’ll have to maintain the workflow definitions so they don’t get out of sync with any changes happening on the API operations they connect with. And, of course, all the maintenance of executing those workflows and exposing them as MCP tools, for instance, also comes at a cost. Keep in mind that the whole solution will have new infrastructure pieces and will have to be maintained over time. By now, it’s clear that you have two paths. On one side, you have the option to keep everything as is and incur rising token costs, higher latency, and unpredictable multi-step agent behavior. On the other side, you can make an investment to implement a capability abstraction layer and keep agent behavior under control. It’s up to you to decide which path you want to take now. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work. 1 Paramanayakam, Varatheepan, et al. "Less is more: Optimizing function calling for LLM execution on edge devices." 2025 Design, Automation & Test in Europe Conference (DATE). IEEE, 2025.

Aug 14, 20262 likes

Designing APIs for the Input-Required World

Agentic workflows don't work well with APIs. Web APIs are stateless by nature. A consumer makes a request, the API processes it, and returns a final response. The next request will be totally new. Unfortunately for the consumers, API servers can't remember who they are. Agentic workflows, on the other hand, need to handle a lot of back-and-forth communication between end users and APIs. In many situations, agents need to ask users for approvals or even extra input. The obvious choice is to keep stateful connections with API servers so that information can be exchanged both ways seamlessly. However, this is a rather expensive choice because it's not easy to scale and maintain. How do you keep thousands (or millions) of open stateful connections at a low cost? What's the solution then? Stay with me to learn more. This article is brought to you with the help of our supporter, n8n. n8n is the fastest way to plug AI into your own data. Build autonomous, multi-step agents, using any model, including self-hosted. Use over 400 integrations to build powerful AI-native workflows. Try n8n now! The challenge with agentic workflows and stateless APIs is related to the need to handle user input as a response to a request. In the beginning, mid-task inputs relied on persistent connections and long-lived server-sent event (SSE) streams. Even though these looked like good solutions, holding channels open forces platform teams to use sticky sessions, making horizontal scaling extremely difficult. Additionally, serverless functions and edge networks can’t hold socket connections open, which excludes the use of inexpensive cloud solutions. On top of all this, whenever there’s a network connectivity issue, all the active SSE connections will suffer. To the point that any multi-step agentic workflows will fail instantly and lose track of what really happened. On the instrumentation side of things, API gateways can’t inspect or rate-limit any callbacks happening inside open SSE streams. You end up with a whole ungovernable solution because of SSE. Is there an alternative? MCP SEP-2322 from February 2026 introduces something that “will significantly reduce the cost of operating MCP servers at scale.” This Model Context Protocol Specification Enhancement Proposal is ground-breaking because it changes the way agents communicate with MCP servers. Instead of keeping connections alive, this SEP defines a “multi round-trip request” using something called InputRequiredResult. In practice, this shifts interactive pauses from connection-level callbacks into predictable, stateless HTTP responses. Yes, that’s a breaking change. And that’s probably why it took more than five months to get from a proposal to a version of the MCP specification. It was only in July 2026 that these enhancements finally saw the light. So, how does InputRequiredResult really work, then? To begin with, every response now carries a required resultType field, explicitly set to either complete or input_required. Let me say that again. Every response now has a required resultType field. Whenever a client receives a response with an input_required resultType, it should ask its user for more information and then retry the request. The MCP multi round-trip request flow (adapted from the MCP documentation, Message Patterns, Multi Round-Trip Requests): (1) a client sends an initial request to the server with the parameters needed for the operation, (2) the server determines that additional information is needed and responds requesting more information, (3) the client gathers the requested information from its user and then retries the original request including the additional information, and (4) the server determines it has sufficient information to complete the operation and responds with the final result. The MCP client then gets the missing information from the user and makes another request. The server now has enough information and, if everything goes well, will respond with a complete resultType. This approach decouples the retries, which can happen at different points in time. Now, there’s no need to keep a stateful connection open waiting for the MCP client to gather input from its user. In turn, this allows the protocol to take advantage of API gateways, proxies, and other network elements that already work well with HTTP. The best thing is that you probably don’t need to implement anything by hand yourself. Since the protocol has been updated, it’s safe to expect that SDKs and libraries for supported programming languages will follow along. The only thing you have to do is adapt your own MCP server to use the very latest version of the protocol library. And what about the API that sits behind the MCP server? How do you adapt it to handle multi round-trips well? One thing is implementing the input-required approach at the MCP server layer. Another thing is making the underlying APIs compatible with this new approach. To fully understand it, let’s see what it really means to say that an input is required. First, it means that somewhere the input parameter must exist. That’s obvious, right? Then, it must be marked in some way as important or even required right from the start. Finally, the MCP server now must treat these inputs dynamically and flag them as required if it really needs them to complete an operation. In practice, at the API implementation layer, that means that all inputs should be treated as optional. Until there’s a situation where they become required. Then, the API should respond with the appropriate HTTP error code, and the MCP should translate it into a multi round-trip. Another drawback to the input-required approach is that not all MCP clients support it yet. What that means is that you’ll probably have to support both scenarios for some time. And that’s an extra cost. At this point, you’re confronted with at least a couple of options. One option is to keep using SSE. You won’t have to make any changes to your existing MCP servers. This sounds like an interesting choice if you control your environments and all your clients are private. The drawback is that you won’t be able to offer the latest MCP features. And, sooner or later, MCP clients will become incompatible with SSE. The other option you have is to adopt the multi round-trip design. While this choice sounds more expensive now, it gives you a resilient, future-proof foundation. The decision is yours. Look at your current gateway metrics, check how your infrastructure handles long-running calls, and decide if your team is ready to design for an input-required world. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Jul 31, 2026

No One Understands What Your API Does

The day you were longing for finally arrived. You deployed the first version of your API. Being able to see the result of months of hard labor feels gratifying. Your API is up and running. No errors. So you and your team go out to celebrate. The next morning, reality settles in. You start looking at analytics only to find out that usage is extremely low. Other than yourself, the developers from your team, and a couple of customers, no one really used your API. When you ask your team why there’s no usage, they can’t explain it. You published the announcement, users reacted positively, and the documentation website has been getting traffic. What’s wrong? This article is brought to you with the help of our supporter, Scalar. Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth. Try Scalar for free! Developers don’t really understand what your API does. Examples that are too abstract, missing workflow information, and unclear capabilities create confusion about why operations exist, not just how to call them. Partners and integrators also don’t understand your API. They try to do a business evaluation of your API, but all they can find is a technical reference. Sales engineers don’t have better luck. Because there’s no clear use-case narrative, deals hang forever in the “what does this even do” stage. The support team can’t understand what your API does. Instead of instructions on how to respond to customers, all they see is a reference document full of jargon. Even product managers can’t fully understand what your API does. The documentation describes technical resources, not jobs-to-be-done. AI agents can’t understand your API. There’s no easy way to infer intent, meaning, or when to use one operation or another. No one understands what your API does. The friction each group felt was a result of what they needed to get their jobs done. Naturally, not everyone went through the same challenges, as not everyone had the same task to complete. What made the API so difficult to understand? In summary, the problem lies in its documentation. But where exactly? It wasn’t its lack of technical detail. To answer where the problem is, we have to focus on what consumers need “to get their jobs done.” Each group felt that the API documentation wasn’t helping them move forward. The documentation was too technical and didn’t take into account the needs of each consumer persona. To fix it, you need to understand what each group really needs from the documentation. You need to add use case walkthroughs that explain which scenarios the API can help with. Business users want to see information about capabilities and benefits that speak their language. Product users want to see user stories and the JTBD that each API operation solves. Support users want to see a list of FAQs for each operation as well as detailed troubleshooting instructions. Partners want to see commercial information and understand how they can make money with the API. Finally, AI agents want to see contextual information. How are you going to add all this information without overloading the documentation? A product manager wouldn’t want to see partner-related commercial information, for example. One way to offer differentiated API documentation is to have multiple API portals. You could have a portal for developers, another one for partners, one more for support users, and so on. This gives you the maximum possible flexibility, as you can have a totally separate website for each set of users. But is it efficient? Well, perhaps if you’re maintaining just a couple of portals. However, if the number of portals grows, the effort to maintain everything becomes prohibitive. What I mean by “maintaining” is not just making sure that the portal is up and running but also updating it whenever you update the API. As the number of portals grows, the chances of having outdated information also grow. What’s the alternative, then? What I suggest is using a single API portal with a single OpenAPI source of truth. That OpenAPI document will hold the elements that are common to all audiences. Having access to it should be enough to know how to use the API. Now, on top of that, you add all enrichment each user group needs to understand the API. With OpenAPI Overlays, you can do it very efficiently. You would create one overlay document for each user group, adding the enriching elements. You could, for instance, make operation descriptions better suited for business users. Or add a troubleshooting section to existing operations. Or even add contextual information to help AI agents navigate the API. Each OpenAPI Overlay has its own document that you can maintain separately from the main OpenAPI file. As you can see, OpenAPI Overlays isn’t hard to use. I wrote about and shared examples here before: So, using OpenAPI Overlays seems like a solid way to differentiate API documentation, right? While that’s true, there are costs in making it work. The first is related to keeping up with changes in the master OpenAPI document. Changes to your main OpenAPI definition can affect the behavior of overlays. Even though you managed to decouple the final documentation, it still depends on the shape of the initial definition. One other challenge has to do with the compilation that has to happen to render the documentation. That’s another piece of software that you have to maintain for every overlay. And finally, something less technical. What is the source of truth, in the end? Does the final documentation even make sense without the overlay? On the one hand, using overlays can fit your API documentation to the needs of different user groups. On the other hand, though, making overlays work can be a costly adventure for you to embark on. You have to measure the costs you’re already incurring by not offering the best possible experience to your consumers. If those are higher than the effort of implementing OpenAPI Overlays, then you know what to do. If not, stick to what you already have. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Jul 22, 2026

The Most Important Step in the API Lifecycle

I learned the hard way how to design useless APIs. I still remember how I would spend most of the time making sure that my API was mapping the underlying data model. Or, how I would obsess over the details of the API definition. Fortunately, those days are long gone now. Now I know that those details are meaningless to consumers if the API doesn't fulfill their needs. Really, what I was doing was designing an API for myself, not the consumers. Is this scenario familiar to you? I suspect you've been through this a couple of times at least. Getting out doesn't have to be complicated. Read on to see how I did it. This article is brought to you with the help of our supporter, Naftiko. Naftiko is a platform that helps organizations manage their technical assets as business capabilities. It provides a central space where teams can define and discover what their services can actually do. By moving the focus away from raw API operations, Naftiko helps engineering and product teams work better together. It was 2006 or 2007, I can't remember exactly. I was working on a project for a big book publisher. My goal was to create an API so that warehouses, printing companies, book shops, and other partners could integrate with the publisher. The API style of choice at the time was SOAP, and along with it came the willingness to model everything around objects. Needless to say, it felt perfect to me. I mean, how else would I design an API about books, right? Right? I made an inventory of all the existing objects and all the possible actions between them. Then I implemented the API and even did a full battery of end-to-end tests. Everything was perfect. Until I shared the WSDL (the SOAP equivalent of an OpenAPI document) with a partner. Their questions and support requests started coming in. "How do I get the author and publisher IDs so I can create a book?" was something no one except me could understand. Partners would have to check if the book author and publisher already existed to get their IDs. Or, they would have to create them instead. This happened because, to create a book, you'd need to send in the author and publisher IDs as numeric parameters. From the consumer's point of view, it didn't make sense. I obviously was oblivious to that. How could I not be? Talking with API consumers is something that would have helped me be aware of their needs and desires. By first understanding users' problems, you can learn what solutions they find valuable. You learn how they go about their days and what tools they use. You learn what the things they value the most are. If you do it on a continuous basis, you'll gain a deep understanding of your audience. And that will certainly lead to better API designs. However, that alone won't guarantee that your API is fully aligned with your consumers. To get there, you need to go through the most important step in the API lifecycle: the API Design validation loop. API Design is, itself, a lifecycle step that decomposes into several blocks. It starts with ideation, then strategy, followed by definition, validation, and, if there's alignment, specification and implementation. Notice that there's a condition to move forward. "If there's alignment." If you and your consumers aren't aligned, you get to repeat the API definition. Each time you pass by the validation loop, you put the API closer to what they really need, not just your own ideas. So, how do you go from theory to practice? What exactly do you need to implement an API Design validation loop? Keep reading. Saying that you have an API Design validation loop is one thing. Executing it properly is something else. The goal of the loop is to make sure that it only ends when all the involved stakeholders agree with the API definition that you’re proposing. That’s all you need to understand to implement it. You can create a fully manual process, automate all the steps, or just some of them. Let’s look at a couple of examples to see what your options can be. Take, for instance, a company that has just one API and a handful of partners. There are changes every couple of months or so. In this case, it probably doesn’t make sense to invest in building an automated process. Having meetings with the stakeholders to present the new design might be just enough. On the opposite side of the spectrum, imagine a team serving several APIs inside a large enterprise. They have hundreds, or perhaps thousands of API consumers. Any change, even a small one, can make the API difficult to integrate with. In this scenario, having a feedback management system in place makes sense. Trying to manually capture the opinions of hundreds of consumers would be a recipe for failure. In any case, having a tool that lets you generate and share an API prototype is a must. People usually like to try things out before sharing their feedback, right? And the longer they spend testing your API prototype, the longer you’ll have to wait. API Design validation easily becomes a bottleneck, especially when many stakeholders are involved. Asking for feedback on a large change means opinions take a long time to arrive. On the other hand, splitting a large change into smaller chunks means navigating the validation loop multiple times. While maintaining a feedback system might seem easy, the cost of delayed API implementation is high. Multiply this delay across all teams and stakeholders, and the process quickly gets out of hand. That’s why API Governance is so important. But that’s a topic for a different time. What matters now is that you have two options. You can continue to implement APIs without knowing what consumers really need. The risk with this approach is that you’ll have to re-design and re-implement your API every time consumers complain. Or, you can just adopt the API Design validation loop and implement exactly what stakeholders care about. Here, the risk is that you end up spending too long in the loop. So, what would you prefer? Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Jul 10, 2026

An A2A Survival Guide for API Owners

Designing APIs for humans leads nowhere. What we once considered a best practice is now obsolete. Yes, human developers are good at understanding sometimes ambiguous API documentation. They can write code that handles errors gracefully and makes up for missing explicit data types. Things like strings that can also be null and integers without a maximum are what make human-led API integration interesting. However, most API consumers now aren't human. We're long past those days. Now, AI agents can discover, make requests, and combine API operations, all on their own. But AI agents aren't as resilient to ambiguity as people used to be. That's why they often fail to understand what an API does and how to use operations in more sophisticated workflows. What can you do to reverse this trend and help AI agents succeed? Stay with me to learn more. This article is brought to you with the help of our supporter, n8n. n8n is the fastest way to plug AI into your own data. Build autonomous, multi-step agents, using any model, including self-hosted. Use over 400 integrations to build powerful AI-native workflows. Try n8n now! Before trying to find solutions, let’s look at the challenge AI agents face in more detail. You can split the problem into three areas. One area has to do with timeouts related to operations that take too long to complete. This has to do in part with the second group of issues, which have to do with errors that are too generic to understand. And, finally, the biggest challenge, in my opinion, is making inter-API requests work well in a reality where state isn’t easily shared between agents. Timeout challenges happen because traditional synchronous REST operations are blocking. In other words, when you make a request, you have to wait until it ends. If the operation takes too long, AI agents will interpret it as a timeout and will disconnect. In this case, AI agents don’t get an error, but many times when they do, they can’t understand its meaning. Whenever an AI agent uses operation parameters wrongly, or when a payload is malformed, many APIs simply return a generic HTTP 400 error. Because there’s no information about what to fix and how to proceed, AI agents simply give up. And that’s not the only time when they give up. They also do it when they don’t know how to move tasks between different AI agents. Situations that involve workflows with several operations require a heavy handling of context and state, which more often than not tends to fail. There’s a solution, fortunately. The first step to finding a solution is to introduce a layer of coordination for workflows involving multiple AI agents. This layer of coordination is the A2A (Agent-to-Agent) protocol. You can think of A2A as the system that allows separate agents to talk, delegate work, and hand off tasks across network boundaries. A2A was created by Google and launched in April 2025 in an ecosystem of more than 50 partners, including Atlassian, Box, and Salesforce. Soon after, Google transferred it to the Linux Foundation to establish neutral governance and encourage wide adoption. The primary goals of A2A include the ability to have collaboration between agents built using different technologies, the encapsulation of the complexity each agent has to deal with, and, of course, having a standardized inter-agent communication. While MCP standardizes the way an agent communicates with exposed tools, A2A simplifies the horizontal communication between agents. Both protocols complement each other. Let’s then see how to implement A2A. The very first thing you need to make A2A work is to have what we call an “agent card.” You can see it as a sort of business card, but for agents, not people. It’s where you advertise what your agent is capable of and how other AI agents can invoke it. Here’s a very simplified example of a card for an agent that handles newsletter subscriptions: { "name": "API Changelog Newsletter Agent", "version": "0.1.0", "description": "Subscribes readers to the API Changelog newsletter.", "url": "https://example.com/a2a", "skills": [ { "id": "subscribe_api_changelog_newsletter", "name": "Subscribe to API Changelog newsletter", "description": "Subscribes an email address to the API Changelog newsletter." } ] } By publishing this card at the /.well-known/agent-card.json location, you’re letting other agents know what yours is capable of. There’s more information you can add to the card to help agents interact, such as authentication instructions. This is just an example, so you can see what’s possible. The second thing you want to do is to shift from synchronous operations to an A2A-compliant asynchronous task state machine. That means that, among other things, operations should immediately return a task_id and then let consumers poll for state information. States let consumers understand how far a task is from being completed. An example of a “happy path” is a task that transitions from the submitted state to working and finally to the completed state. Other states include input-required, failed, and canceled. To avoid having to periodically poll to get the latest task state, one good practice is to implement SSE and notify any consumers instantly as states change. And speaking of good practices, there’s one way to avoid failing whenever there’s a bad input. Instead of switching immediately to failed, you can return the input-required state and let the consumer agent ask its human user for help. These initial steps should get you started with the A2A protocol. But there’s more, much more. While supporting A2A can be interesting, it doesn’t come without a price. Upgrading your API to move away from synchronous operations and support the asynchronous state machine is no piece of cake. If you start thinking about it, your backend must now manage task persistence, state stores, and polling or streaming logic to track long-running operations. Adding to that, you must also handle automated identity verification to make sure you know who’s calling you. In essence, you must pick a robust security framework such as OAuth2 or signed JWT to ensure that agents are verified and can be rate-limited. And the final piece of frustration is related to testing. While procedural synchronous code is easy, testing asynchronous workflows spread across multiple agents and multiple operations isn’t simple. Knowing all the pros and cons is important. One option you have is to continue as you are and keep your APIs unchanged, targeted at human consumers. If you follow this path, you accept that you’ll gradually become isolated as the rest of the industry moves towards multi-agent ecosystems. The other option is to invest heavily in the engineering effort to make the switch to A2A now. Yes, there’s a cost, and there are associated risks, but the rewards can be even bigger. In the end, it’s your call. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Jun 26, 2026

The Taxonomy of API Operations

API documentation is always incomplete. But that doesn't matter if those who consume it are developers. Like any other human being, developers have the power of intuition. And that makes all the difference. Unlike an AI agent, a developer can go through a long list of API operations and intuitively group them by intent. Or infer the format for an undocumented data type based on information available elsewhere. Or even understand that an operation is legacy just by looking at its name. When AI agents see every API operation as identical in nature, they face an enormous cognitive load. They become disoriented when operations take too long to complete or in the face of a potential risk. In other words, they spend more tokens and require more help from humans. What is the solution, then? Keep reading. This article is brought to you with the help of our supporter, Scalar. Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth. Try Scalar for free! So, what exactly is the problem AI agents have with the API documentation you and I have been creating? Actually, there’s more than one kind of problem. And they all have to do with the ability to understand what each operation really does. Because of that, agents have to scan the whole API documentation every time just to get the right combination of operations. Let’s look at the most important challenges AI Agents face today while doing operation discovery: Unknown side effects: there’s no way for an AI agent to know if an API operation produces side effects just by looking at its name. How would you know, for example, if POST /orders simply creates an order entry or triggers a chain of events that eventually end up in shipping some product to a customer? Runtime uncertainty: an AI agent can’t understand if an API operation can perform a search or if it simply returns a static list. Take, for instance, the GET /products operation. Does it always return the same list of products, which you can filter after the fact, or does it perform a dynamic search on a live product catalog? Orchestration fragility: if an API doesn’t explicitly declare its high-level orchestration paths, an AI agent is forced to build its own step-by-step plans. Operations such as POST /users can be a part of a bigger workflow, which involves creating and billing a new customer. Connection timeout: AI agents treat all API operations in the same way. If an operation is taking too long, an AI agent assumes there’s a timeout. However, it’s normal for some operations to take a long time to finish. POST /reports/generate, for example, looks like it will take some time to complete. However, to an AI agent, it might seem like any other operation. Constraint blindness: it’s very hard for an AI agent to infer awareness of its own identity, privileges, and constraints. Without that information, AI agents will attempt to use API operations until they receive errors, which leads to wasted resources. How would an AI agent know that an operation like GET /me could be useful to understand its own identity and privileges? Inefficient polling: there’s no way for an AI agent to remain idle waiting for an event to finish. It will try to periodically get information about the event. Suppose the agent executes an operation to perform a bank transfer. The next logical step would be to periodically call GET /transfer/{transferId} to understand if the transfer with the corresponding ID is finished. Loop saturation: AI agents that have to process a large volume of data will simply loop over individual operations until their task is finished. This situation usually leads to reaching API rate limits or, even worse, to being flagged by a gateway as a DoS attack. Blind execution exposure: AI agents don’t know how to separate safe experimentation from critical production mutations. A human would try an operation like POST /charges against a mock before going to production. However, an AI agent doesn’t have that intuition. Many of these problems aren’t exclusive to AI agents. If developers interacting with an API don’t have enough knowledge about it, they’ll also face similar challenges. Having good documentation helps, but many times it’s not enough. So, what else can you do about it? One solution is to stop thinking of API documentation simply as a way to expose resource and collection names. But that’s too dramatic, and we don’t want to kill what already exists. Instead, what I propose is to augment the existing API naming conventions with an operation taxonomy focused on behavior. The idea is to group operations into categories based on how they function and the impact they have. This distinction allows AI agents to understand not just the resources that operations interact with, but also their scope, safety, and eventual cost. How would such a taxonomy work, then? The taxonomy of API operations groups them into eight categories based on their behavior and system impact. By classifying operations as atomic, workflow, asynchronous, introspective, discovery, reactive, bulk, or simulated, you create a predictable map that helps machines navigate APIs safely. Here are the eight categories, in more detail: Atomic operations: granular, single-purpose resource manipulations, e.g., GET /customers/:id, POST /products. They offer precise control but high reasoning overhead when you need more than one atomic operation to complete a task. Workflow operations: high-level, intent-based operations that encapsulate multiple steps into one single request, e.g., Stripe’s POST /v1/checkout/sessions, HubSpot’s POST /v1/crm/pipelines/merge. Asynchronous operations: long-running background jobs that break the immediate request-response cycle, returning a 202 Accepted response and a status operation for polling. Introspective operations: meta-calls that give consumers information about themselves or the context they’re interacting with the API, e.g., rate limits, identity, credits, and security token scopes. Discovery operations: dynamic ways for consumers to explore available capabilities or product catalogs at runtime, e.g., GET /products, GET /operations. Reactive operations: event-driven mechanisms like Webhooks or Server-Sent Events, where the API pushes data to the agent automatically. Bulk operations: mass processing operations designed to handle arrays of items in one request to prevent rate-limit exhaustion. Simulated operations: dry-run capabilities that validate logic without mutating production data, e.g., using a dry_run parameter, POST /invoices/preview. One thing I want to clarify is that operations can be on more than one category. Similarly, there are operations that you’ll have a hard time categorizing. That happened to me with operations that mostly didn’t make sense in a RESTful way. Things like DELETE /products. Does it delete all the products? Or, what does it do? Finding one of these operations certainly gives you the opportunity to redesign your API. I’d iterate on that until finding a good alignment between the behavior I want the API to convey and the potential needs of consumers. Distribution of API operation categories after analyzing 52,238 OpenAPI documents from public GitHub repositories. Taxonomy was inferred by comparing the morphology of each API operation with a set of pre-established heuristics. While the atomic and discovery categories dominated, 3.5% of operations were considered uncategorizable. As you can see, sometimes there are difficulties in following this classification system. While the first challenge is finding the right category, there are other issues to consider. One is related to how you store the category information inside an OpenAPI document. I suggest using something like an array attribute named x-taxonomy, which you can put inside an operation and add multiple categories to. This will make the taxonomy machine-readable, which is our goal anyway. Another challenge has to do with the inevitable category drift. As an API evolves, what was first considered an atomic operation might become a workflow. Or something else. Overall, you’re introducing a new layer of information that you’ll have to keep in sync with any future API changes. Feeling unresolved? That’s because the decision to adopt this taxonomy depends on your primary consumer. As far as I see it, you have two options. If your API is purely for traditional developer-built integrations or direct human consumption, the effort to add a taxonomy might be higher than its benefit. However, if you’re targeting AI agents, a taxonomy is something you need to have. Without it, machine consumers won’t be able to make the most of your API in a cost-effective way. And they’ll probably look elsewhere, which is something you want to avoid, right? Well, I’ve made my point. The decision is in your hands now. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Jun 20, 20261 likes

Tealium Context API, Blockworks + Messari, ServiceNow Data Leak

This is issue 2026.24 of the API Changelog, a mix of API news, commentary, and opinion. In this issue, you'll get to know the most relevant API-related information from the week of June 8, 2026. Subscribe now, so you never miss an issue of the API Changelog. What are the steps to create a successful API product? Learn about it by reading "Building an API Product." The book targets Product Managers and non-technical people who want to know what it takes to build API products. If this isn’t the book for you, perhaps someone you know would like to learn from it. Share it with your contacts and help us spread the word. Get a copy of the book now! As we can all see, the industry is moving quickly toward an economy built on AI and agents. And this is changing how we design, secure, and monetize APIs. Many platforms are moving away from the old, rigid frameworks. The choice is to pick technology that makes it easy to do things like showing customer data in real time or delivering instant audio streams in many languages. But this move toward automation brings new risks to infrastructure. Because of these vulnerabilities, we’re seeing a push for better security. Companies are now focusing on runtime scanning and identity governance. They’re also building compliance layers designed to keep autonomous agents under control. The friction of moving off legacy enterprise infrastructure has long been a primary roadblock to technical agility. Knowing that, Kong launches Ascent to help companies get agentic AI-ready. Built specifically to accelerate transitions away from aging platforms such as MuleSoft and Apigee, Kong Ascent combines automated code parsing and policy classification to migrate workloads to the unified Kong Konnect ecosystem. Kong offers AI-assisted, human-in-the-loop automated API migration services available through Kong Professional Services. Simultaneously, data availability at the edge is reaching lower latencies. Tealium’s rollout of the Context API addresses the long-standing divide between the deep data pools of centralized warehouses like Snowflake and the immediate data demands of live customer sessions. Functioning as an evolution of its legacy Moments API, this model-neutral presentation layer serves real-time insights with a response window of just sixty milliseconds, entirely bypassing the need for complex microservices or expensive data mirroring. The Customer Data Hub is Tealium’s central platform for end-to-end management of customer data. As frontier models push deeper into production environments, balancing elite capabilities with organizational safety boundaries requires innovative API architectures. Anthropic’s general release of Claude Fable 5 illustrates this challenge by bringing the reasoning capabilities of its highly restricted, security-focused architecture to mainstream developers. To mitigate national security risks and prevent model exploitation without completely shutting down access, Anthropic has engineered a clever multi-model routing pattern directly within its Messages API. Update: Anthropic has since disabled Fable 5. According to their statement, the “US government, citing national security authorities, has issued an export control directive to suspend all access to Fable 5 and Mythos 5 by any foreign national, whether inside or outside the United States, including foreign national Anthropic employees.” This intersection of advanced automation and raw data access is also reshaping technology, media, and intelligence markets. Blockworks’ recent acquisition of rival research platform Messari for a reported eight-figure sum reflects a major consolidation wave driven by institutional demand for structured crypto data. Bolstered by its recent valuation surge, Blockworks is leveraging Messari’s established API engine to create a dual-sided marketplace for token investor relations and verified issuer records. A push for standardized, programmatic access is transforming traditional financial networks. Alkami Technology’s deep integration with Yodlee marks a major step forward for open banking by moving data aggregation services entirely to the industry-standard Financial Data Exchange API. This structural shift replaces traditional screen-scraping methods, which strained banking servers and required consumers to risk exposing their actual passwords to external apps. Meanwhile, the voice processing field is experiencing a similar wave of democratization with the launch of Krisp’s Voice Translation v3 API. This release converts an enterprise-grade, low-latency translation engine into a self-serve platform for software engineers. Instead of forcing developers to manually string together separate models for transcription, translation, and text-to-speech synthesis, the new platform provides a single, unified audio infrastructure layer. The travel industry is also undergoing an API overhaul designed to eliminate legacy friction. Travelport’s formal launch of its TripServices platform introduces a modern, cloud-native API designed to normalize fragmented multi-source travel data into a clean, structured schema. Financed by a substantial technology investment and developed alongside industry partners, this platform marks a strategic shift toward an AI-ready travel ecosystem. On the programmatic trading side, multi-asset broker XBTFX has introduced a flexible, code-driven trading API designed to transition its platform into a highly adaptable financial infrastructure layer. Tailored for algorithmic traders and autonomous financial bots, this interface splits operational logic into two distinct communication paths. The risks of misconfigured interfaces were highlighted by a recent security incident involving ServiceNow, which exposed how small gaps in authentication logic can lead to massive data leaks. The vulnerability originated from an internet-facing Scripted REST API endpoint that shipped with its authentication properties inadvertently disabled. This oversight allowed unauthenticated external requests to bypass session checks and query internal instance tables housing sensitive IT workflows, asset inventories, and system tokens. This reality has catalyzed a new wave of deep governance adapters built specifically around Anthropic’s Claude Compliance API, with platforms like Linx Security, Opsin, TrendAI™, and Axonius integrating with this compliance stream to give security operations teams out-of-band visibility over enterprise AI interactions without introducing inline network friction: Linx Security uses this programmatic link to build comprehensive identity access graphs, mapping explicit employee roles, monitoring permissions, and tracking the lifecycle of internal keys to eliminate unmanaged credentials. Opsin addresses compliance in regulated sectors like healthcare and finance, utilizing dedicated Compliance Access Keys to review user and agent intent against internal guidelines to stop accidental data exposure before it leads to an incident. TrendAI™ embeds this telemetry directly into its Vision One ecosystem, deploying local and cloud-based logging models that stream conversation logs and file transfers into XDR engines to flag advanced prompt injections and code leaks while respecting strict regional data rules. Axonius connects through its own specialized adapter to pull workspace artifacts directly into its asset management cloud, where the platform cross-references authorized tenant profiles with local device inventories and software states to uncover unmanaged shadow AI instances. As automated threat models become faster and more sophisticated, application perimeters require dynamic, real-time protection. F5’s expansion of its Web Application and API Protection solutions directly answers this threat vector, where malicious AI tools are deployed to scan, reverse-engineer, and exploit exposed software vulnerabilities at machine speed. This week’s updates show that APIs are finally maturing beyond simple data pipelines into the nervous system of an agentic economy. Engineering teams must now design directly for machine consumers, whether managing financial data, travel sales, or AI threats. As the line between application logic and AI disappears, success belongs to organizations that prioritize low latency, clean schemas, and solid compliance. Thanks for reading, and we’ll see each other next week! Thanks for reading The API Changelog! Subscribe now for free.

Jun 16, 20261 likes

From Gateway Governance to Capability Orchestration

API gateways are useless. Well, not yet, but if they don’t adapt to API capability consumption, they will for sure. What do I mean by that? API gateways were designed for predictable traffic driven by developer-made integrations. In this reality, anything that looks suspicious is treated like an outlier. A burst of requests to the same operation with small changes in parameters. An unanticipated combination of requests to different operations. Or simply paginating through a very large result set. Yes, an API gateway can work perfectly when its only job is to check authentication tokens, apply rate limits, and route HTTP requests to specific microservices. The challenge is that today’s reality has more to do with dynamic, ephemeral workflows and less with fixed static API integrations. The API gateway can’t understand the intent behind certain combinations of requests. And that’s a real issue because those combinations are what agents see as the business capabilities they need. How can you address this problem now and make your APIs agent-friendly? Keep reading to explore solutions. This article is brought to you with the help of our supporter, Naftiko. Naftiko is a platform that helps organizations manage their technical assets as business capabilities. It provides a central space where teams can define and discover what their services can actually do. By moving the focus away from raw API operations, Naftiko helps engineering and product teams work better together. Before analyzing solutions, let’s understand the problem in more detail. Let’s look at how an LLM can interact with an API. Even though an LLM could use a custom point-to-point connection with an API, the tool of choice these days is the MCP. It gives AI agents a standardized way of identifying and interacting with available tools. The MCP server would then convert a request to one tool into one or several requests to API operations. I can already see a few challenges with this approach. But what happens when there’s no API to connect with? You can also have MCP servers that interact directly with a database, even though you can’t say that’s a good practice. What’s important is that MCP gives AI the agency to access API operations and backend systems and convert them into capabilities on the fly. Ephemerally. Think for a moment about the technical complexity of managing a fleet of this kind of capabilities. API gateways follow strict routing rules, often managed by a complex control plane. When an AI agent makes a request to one tool, the MCP server might need to call several API operations. To the API gateway, this looks like three unrelated requests. Because of that, there’s no way for it to enforce a unified semantic policy. In other words, API gateways lack the awareness that a sequence of distinct requests belongs to a single, high-level business capability. Now you can fully understand the problem we’re dealing with. Fixing it requires a fundamental shift away from forcing every request through an API gateway. Instead, you need to move to a control plane that uses declarative capability definitions. Why? Because it decouples the policy enforcement from the network topology. It places the capability orchestration above your infrastructure to automatically translate high-level business definitions into workflows composed of API operations. One way to achieve this is to add the functionality to the API gateway itself. That’s not the approach I would take, however. Instead, I’d implement a spec-driven integration fabric. I’d make it so that it would understand OpenAPI, AsyncAPI, MCP, and Arazzo, and instantly expose groups of operations and workflows as tools. Each tool would then map to a business capability. It sounds interesting, but how can you make it happen? One way to implement this solution involves combining an open-source multi-protocol gateway with a control plane that can understand workflows. Open-source solutions like the agentgateway, ContextForge, and Apache APISIX are good examples of gateways that can handle more than one protocol. The trick here is being able to execute full workflows that combine operations from several APIs. Look at this mockup example declarative configuration that defines a checkout capability. It defines two sources of operations and exposes the checkout capability as an MCP tool. metadata: name: checkout-capability spec: tool: name: "execute_checkout" description: "Handles the complete customer checkout workflow." definition: openapi: "https://example.com/apis/orders.yaml" execution: arazzo: "https://example.com/workflows/checkout.yaml" workflowId: "checkoutWorkflow" policies: - type: "token-budget" limitPerMinute: 50000 - type: "rate-limit" requestsPerMinute: 100 A configuration document like this would help a multi-protocol gateway interpret incoming requests and perform execution and protocol translation. Following the example, whenever an AI agent calls the checkout tool, the gateway catches the request, looks at the Arazzo definition to see the correct sequence of API calls, and executes it. It also enforces rate and token limits at the logical capability level instead of checking isolated API operations. Looks simple, right? However, implementing it isn’t as easy as it looks. Transitioning to a capability-driven orchestration model doesn’t happen without effort. There are real engineering and organizational costs you need to take into account. And the most important one isn’t even related to technology. No, the biggest effort to drive capability orchestration has to do with change management. If you’re not following an API design-first approach yet, you’ll have to. Every capability needs to be backed by properly documented API operations. Inputs and outputs have to be properly modeled, documented, and tested so they work independently of how they’re consumed. If your team isn’t doing this yet, they have to. But there’s more. Your platform engineering team, or whoever takes care of your infrastructure and traffic, will face a technical learning curve to integrate the distributed control plane into existing deployment pipelines. They’ll have to do things like configure sidecars for traffic enforcement and change monitoring tools from tracking simple HTTP status codes to tracking semantic tokens, policy violations, and actual business capability usage. As things continue to evolve in the agentic workflow space, the pressure to make a decision will increase. Should you continue adding plugins and patches to your existing API gateway? Or, should you make the move to a capability orchestration solution? If I were you, I’d spend some time understanding how many standalone MCP instances there are, and how many hidden API operations they’re exposing. I’d seriously consider moving to a declarative approach similar to the one I described before. But I’m not you, and I can’t decide for you. At the end of the day, the decision comes down to whether you want to spend your days managing MCP and workflow sprawl or orchestrating a set of well-documented business capabilities. The choice is now yours. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

Jun 12, 20261 likes

Postman AI Engineer, Strava IPO, Fingerprint AI Assistant Detection

This is issue 2026.23 of the API Changelog, a mix of API news, commentary, and opinion. In this issue, you'll get to know the most relevant API-related information from the week of June 1, 2026. Subscribe now, so you never miss an issue of the API Changelog. What are the steps to create a successful API product? Learn about it by reading "Building an API Product." The book targets Product Managers and non-technical people who want to know what it takes to build API products. If this isn’t the book for you, perhaps someone you know would like to learn from it. Share it with your contacts and help us spread the word. Get a copy of the book now! The tech sector is going through a big shift right now. As autonomous AI agents become more common, the way we think about APIs has to change. We can no longer build APIs just for human developers to read documentation and write code. Instead, we need to design programmatic infrastructure built for machine-to-machine communication. Leading this transition is Postman, which has fundamentally re-architected its core environment to be AI-native through the introduction of its “AI Engineer.“ Moving past basic chat assistants, this system deploys an autonomous Agent Mode that operates directly on an AI-optimized Collection v3 YAML format, enabling LLMs to independently handle the entire API lifecycle from initial schema design and contract testing to continuous debugging. The Context Graph is a part of Postman’s AI Engineer stack. It’s a “living map of the APIs and services across an organization.” While companies like Postman push toward an agentic future, other tech giants are struggling to get their programmatic interfaces out the door, highlighting the intense pressure to monetize massive infrastructure investments. Meta Platforms has repeatedly delayed the public rollout of the developer API for its flagship Muse Spark AI model due to persistent software bugs and underlying system issues. While Meta AI Chief Alexandr Wang initially promised the API was coming soon, the subsequent two-month delay has intensified investor scrutiny regarding how quickly the company can monetize its projected $125 billion to $145 billion capital expenditure boom. Meta has since confirmed that the API is undergoing testing with early partners and is slated for a broad release later in June 2026 to help close the enterprise distribution gap with rivals like OpenAI and Anthropic. Because AI agents lack human intuition and require hyper-precise guidance to navigate backend systems, enterprise AI firm Jentic has launched a free, open-source API Scoring tool under the Apache 2.0 license. Integrating directly into CI/CD pipelines, Jentic’s tool automatically audits OpenAPI documents across dimensions like machine usability and AI discoverability, ensuring that exposed corporate endpoints are optimized for reliable agent execution rather than human interpretation. Jentic grades APIs across six dimensions: foundational compliance, DX, AI-readiness, agent usability, security, and AI discoverability. The explosion of shadow APIs has introduced critical enterprise security and governance challenges. Addressing this invisible attack surface, Akamai Technologies has partnered with cybersecurity firm GM Sectec to deliver a unified compliance framework that continuously discovers and monitors real-time API behavior. By integrating GM Sectec’s non-human identity governance with the Akamai API Security platform, the solution maps machine-to-machine API calls and strictly audits data-access privileges, helping enterprises comply with stringent regulations like PCI DSS v4.0.1 that treat autonomous agents with the same security scrutiny as human users. Simultaneously, device intelligence leader Fingerprint has addressed client-side validation gaps by launching the preview of its AI Assistant Detection alongside a platform-agnostic Automation Intelligence API. Because frontier AI models from OpenAI, Anthropic, and Google bypass traditional JavaScript browser checks by pulling web data directly through backend HTTP requests, Fingerprint’s new API operates directly at the middleware or CDN edge to cryptographically verify legitimate AI assistants and immediately block malicious scraping bots spoofing AI user-agents. This urgent need to defend proprietary datasets from aggressive model training has triggered severe platform countermeasures, most notably from fitness-tracking social network Strava as it prepares for an initial public offering (IPO). Facing a staggering 448% surge in developer applications driven by low-quality, zero-code AI tools hammering its infrastructure, Strava has declared war on unauthorized scrapers by clamping down on its data ecosystem, deprecating public club endpoints, and introducing a flat $11.99 monthly subscription fee for standard API access to establish a highly defensive data moat for public investors. On the other hand, Indian AI startup Atomesus has entered the foundation model market with its Cipher 8B language model, pairing the launch with a public inference API and a massive free credit program offering up to $10,000 for development teams. Capable of processing up to 130,024 tokens via standard API calls, Cipher 8B aims to fuel the next wave of enterprise automation and multi-step agent workflows without the overhead of local infrastructure. To streamline the consumption of these rapidly multiplying models, Ukrainian developers have launched a domestic, unified LLM API platform that acts as a single point of integration for over 400 distinct models. This unified API abstracts the complexity of maintaining separate pipelines for competing platforms like GPT, Claude, and Gemini, featuring an “EvalLab” module that lets software teams programmatically test identical prompts across different models to compare latency, cost, and quality in real time with zero price markup. With the LLM API, Ukrainian companies can integrate with more than 400 AI models using a single interface. Meanwhile, optimization platforms are focused on making this programmatic data directly actionable within native marketing stacks. OtterlyAI has launched a public API alongside a community-driven marketplace of over 101 production-tested workflows, liberating its Generative Engine Optimization (GEO) data from internal dashboards. To demonstrate the power of this API, OtterlyAI paired the release with a single-file Claude Skill, allowing Anthropic’s Claude to programmatically ingest real-time brand performance and search visibility metrics directly into chat interfaces. Beyond data extraction and analysis, the API ecosystem is establishing the foundational transactional layer required to achieve true machine-to-machine economic autonomy. Solving a major friction point where AI agents lacked secure, network-compatible financial rails, stablecoin infrastructure provider Crossmint has launched its public Agentic Cards API in partnership with Visa Intelligent Commerce and Basis Theory. This API allows developer platforms like Claude Code and Zo Computer to issue tokenized, short-lived payment credentials backed by PCI-compliant vaults, enabling AI agents to autonomously complete purchases within strict spending limits without ever exposing raw credit card numbers. Ultimately, the API landscape is no longer just a technical bridge for connecting software applications. As frontier labs scramble to iron out backend bugs and deliver reliable model APIs, the companies that successfully lower programmatic friction while enforcing strict governance will inevitably dictate the speed and safety of the next machine-driven economic wave. Until next week! Thanks for reading The API Changelog! Subscribe now for free.

Jun 9, 20261 likes

Blackmagic AI Gateway, Didit $6M, 42Crunch Agentic DevSecOps

This is issue 2026.22 of the API Changelog, a mix of API news, commentary, and opinion. In this issue, you'll get to know the most relevant API-related information from the week of May 25, 2026. Subscribe now, so you never miss an issue of the API Changelog. What are the steps to create a successful API product? Learn about it by reading "Building an API Product." The book targets Product Managers and non-technical people who want to know what it takes to build API products. If this isn’t the book for you, perhaps someone you know would like to learn from it. Share it with your contacts and help us spread the word. Get a copy of the book now! This week, I have noticed that the programmatic economy is accelerating as traditional financial infrastructure, generative media, and enterprise DevSecOps converge onto unified API planes. From institutional capital markets to the foundation models powering autonomous agents, this week’s movements highlight a structural shift toward eliminating manual friction and driving down token-level overhead to achieve true machine-to-machine automation. Institutional digital asset markets took a major step forward with Caladan’s launch of its API Liquidity service, an infrastructure rollout providing automated, programmatic access to deep, aggregated digital asset liquidity across more than 100 distinct tokens. In this environment, the API serves as the core technical bridge connecting institutional trading desks directly to Caladan’s multi-venue liquidity engine, allowing algorithmic platforms to bypass manual user interfaces. Simultaneously, Citi Investor Services has expanded Financial Information eXchange (FIX) API connectivity to its proprietary, global exchange-traded fund platform, ACES (Advanced Citi ETF System), specifically targeting clients across the Asia Pacific region. Initially rolled out in Australia with a planned expansion to Hong Kong, this integration allows institutional Authorized Participants to link their internal order management systems directly to Citi’s platform via a standardized communication gateway. Further downstream in the corporate banking sector, Garanti BBVA has launched a new BKM-integrated Request to Pay API designed to modernize digital payment collections for corporate clients, commercial businesses, and SMEs. Built directly on the open banking infrastructure of the Interbank Card Center and the Central Bank of Türkiye’s FAST instant-payments network, the API functions as a secure communication pipeline linking a business’s internal ERP or billing software to the bank’s digital channels. The enterprise content landscape is also adjusting to this programmatic shift, marked by Law.com and current awareness platform Vable announcing a strategic API integration. This milestone represents Law’s first-ever commercial API content partnership, designed to embed its trusted legal intelligence directly into the platforms that legal professionals use daily. In this deployment, the API acts as an automated ingestion and delivery engine, allowing Vable to programmatically pull full article content, headlines, and summaries from the entire Law and NewsVault archive to enhance backend search relevance and accuracy. Agentic DevSecOps and Identity Verification steps up as generative AI continues to enable autonomous agents to construct and deploy production software at machine speed, APIs have fundamentally become both the primary attack surface and the ultimate control plane of enterprise cloud architectures. To address this paradigm shift, 42Crunch announced a breakthrough integration with Anthropic’s Claude Code, introducing dedicated AI coding plugins that unlock an autonomous, end-to-end Agentic DevSecOps model for the enterprise. Operating directly within the AI agent’s active coding workflow, the 42Crunch plugin provides real-time static and dynamic API security testing, automatically auditing OpenAPI contracts and scanning for OWASP Top 10 vulnerabilities the moment code is generated. On the identity and compliance front, Spain-based startup Didit secured an additional $6 million in Seed funding, raising its total capital to $7.5 million to scale its global, AI-native infrastructure designed to intercept synthetic fraud, deepfakes, and automated network attacks. Didit delivers its security stack through a single, developer-first API that unifies Know Your Customer, Know Your Business, transaction monitoring, and crypto wallet screening into a modular, programmable surface. The global AI price war reached a permanent baseline as Chinese AI startup DeepSeek informed developers that its temporary 75% promotional discount on its flagship V4-Pro model API is now permanent. Following the conclusion of the promotional period, the company permanently adjusted its first-party API rates to $0.435 per million input tokens for cache misses and $0.87 per million output tokens, alongside a prefix-cached input rate of $0.003625 per million tokens. In tandem with shifting core inference economics, fal has launched as the official day-0 API partner for Krea 2, the debut foundation image model trained entirely from scratch by creative AI lab Krea. Aimed at giving developers granular aesthetic control over raw, niche, and experimental visuals without the overly polished look of legacy media models, Krea 2 is now accessible via a production-ready API hosted on fal’s developer-focused cloud. To simplify managing these expanding frontiers, Blackmagic AI announced a unified, production-ready AI gateway designed as a direct, cost-efficient alternative to OpenRouter for developers managing complex, multi-model workflows. Operating behind a single OpenAI-compatible base URL and a solitary API key, the gateway functions as an abstraction and routing plane that bridges developer applications to 13 distinct AI providers, including OpenAI, Anthropic, Google, DeepSeek, and Black Forest Labs. Finally, AI web data platform Thunderbit expanded its ecosystem into infrastructure-level tools with the launch of a high-fidelity Web Data API, an MCP server, and a CLI. Designed to programmatically transform complex, structurally dynamic websites into clean Markdown or structured JSON schemas for LLMs and retrieval-augmented generation (RAG) pipelines, the suite is powered by two distinct AI engines. Thunderbit Distill acts as an adaptive HTML-to-Markdown parser that ignores fragile, legacy CSS selectors to extract semantic web content without boilerplate elements, while Thunderbit Extract maps live URLs directly into developer-defined JSON structures. Ultimately, this week’s developments underscore an industry-wide push toward deep ecosystem integration and the systemic reduction of engineering friction. Whether by abstracting complex financial data streams via standardized protocols, establishing autonomous security guardrails within agentic workflows, or permanently reducing the cost of frontier model token delivery, the API economy is rapidly moving beyond simple data piping. The emerging standard favors highly modular, open-access, and developer-centric architectures designed to support a scalable, machine-first operational landscape. Looking forward to next week’s updates! Thanks for reading The API Changelog! Subscribe now for free.

Jun 2, 2026

Fixing the MCP Onboarding Mess

MCP is becoming the standard way of consuming APIs. Well, not just APIs, to be fair. It can connect AI agents to anything, from databases to home devices like lamps and switches. With such a diversity of possibilities, any friction that you can remove from client registration is welcome. But, how does an AI agent securely prove its identity to an MCP server it has never connected with before? Let's look at what a person would do. A human would probably go to a website, sign up, create an OAuth client, and copy the client ID and secret along with a redirect URI into a local configuration file. Too many things could go wrong. And many did. And too many times, people would simply give up. So, how can you solve all this mess? Stay with me. This article is brought to you with the help of our supporter, n8n. n8n is the fastest way to plug AI into your own data. Build autonomous, multi-step agents, using any model, including self-hosted. Use over 400 integrations to build powerful AI-native workflows. Try n8n now! The best way to eliminate manual effort is to automate it. And that’s exactly what we did. In March 2025, MCP introduced a recommendation to use the OAuth 2.0 Dynamic Client Registration (DCR). This was the perfect solution to the onboarding friction. However, it created another problem. But before that, if you don’t know what DCR does, here’s a quick refresh. When a new OAuth client instance starts, it automatically sends an HTTP POST request containing its metadata to the authorization server’s /register endpoint. The server dynamically registers the client, saves its details to a database, and returns a unique client_id. There, a new OAuth client is now registered, and no human was ever involved in the process. While this works for static, long-lived clients, it’s completely useless in the world of AI agents and ephemeral MCP clients. There are three main problems with this approach. The first one has to do with sprawl. Every time a new AI agent instance starts, it initiates a new DCR request. The authorization server’s database quickly becomes cluttered with thousands of orphaned client registrations. Most of these records are never used again, yet they must be stored and indexed. Then you have the problem of server-side request vulnerabilities. Leaving a registration endpoint wide open to the public is an operational hazard. Malicious actors can easily flood the /register endpoint with automated requests, consuming database connections, exhausting disk storage, and causing immediate Denial of Service (DoS). And, finally, you have to deal with potential revocation and auditing nightmares. How do you audit a system with thousands (or millions) of dynamically registered clients? Distinguishing between a legitimate, inactive agent and an old, compromised key becomes an administrative impossibility. You see, what was born as a solution to the manual onboarding friction quickly created a new problem of its own. What can you do to solve it? Go back to manual onboarding? Keep reading to find out. The solution to the sprawl that DCR introduced is to make client registration less dynamic. By doing so, every time you register the same AI agent, the client information will be the same. But to do that, there must be a way to store client information so that the authorization server can use it. In November 2025, MCP changed its recommendation to something called Client ID Metadata Documents (CIMD). While this is still an early IETF draft, it’s looking very promising. How does this work then? Well, to begin with, we stop forcing the authorization server to store metadata for every client. Instead, with CIMD, metadata is stored on a URL managed by the client. The client then uses that URL as its client_id. With this approach, the authorization server no longer needs a registration database. It simply fetches the metadata document on demand to process each authentication request. Looks quite smart, right? So, how do you implement it? To support CIMD, your authorization server must replace static database queries with an on-demand resolution and validation engine. Let’s start by understanding how your server can extract OAuth client information. When an OAuth authorization request arrives, the server must inspect the incoming client_id parameter to determine if it’s a URL or a legacy string. If the client_id is a valid URL, it will treat the request as CIMD. Then, it must read the CIMD document by requesting it from the given URL. To avoid performance degradation, having a cache layer at this point can be a good idea. You shouldn’t cache the document forever, though. You can use the information provided by the client’s HTTP Cache-Control headers. If there’s no cache information, use a reasonable timeout, like 24 hours. After you have grabbed the client’s metadata document, you must run three non-negotiable checks before accepting the client’s identity. The first, and easiest one, is to verify if the client_id value inside the document is exactly the same as the URL where the document is located. Then, as a security measure, you should guarantee that the redirect URLs in the document all share the same origin as the client_id URL. And, finally, you should set the appropriate authentication scheme depending on the public or confidential nature of the client. For public clients, you should enforce PKCE, while private clients should work with public keys obtained from a JWKS URL. With all this, you should be ready to support CIMD on your authorization server. As you can see, while CIMD sounds elegant, implementing it is quite complex. On top of the complexity, you also have to deal with potential security traps. I’m thinking of things like SSRF, where anyone could make your authorization server use private or internal credentials. Or things like cache poisoning, metadata URL downtime retries, and denial-of-service loop attacks. Because you need to make outbound HTTP requests to arbitrary URLs, you get exposed to numerous types of risks. On top of all this, there aren’t a lot of open-source or even commercial CIMD solutions because everything is still new. Identity providers are all still looking for client_id values in a local database. You’d need to refactor the system you’re using or wait for it to support CIMD. Ultimately, you have to make a strategic architectural decision. You have two options. On the one hand, you can continue to use manual configurations or maintain your existing DCR implementation. It means writing and running automated cleanup scripts to sweep your database of dead client registrations, accepting the administrative overhead of manual key management, and dealing with developer friction during setup. It is painful, but it is a predictable, familiar pain. On the other hand, you can invest the engineering weeks required to build a hardened, SSRF-resistant, highly available CIMD validation engine. The industry is moving toward stateless agent identity. Will you build the infrastructure to support it, or will you continue managing the database bloat? Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

May 29, 20262 likes

Anthropic + Stainless, Benji $6.25M, Snyk Claude Integration

This is issue 2026.21 of the API Changelog, a mix of API news, commentary, and opinion. In this issue, you'll get to know the most relevant API-related information from the week of May 18, 2026. Subscribe now, so you never miss an issue of the API Changelog. What are the steps to create a successful API product? Learn about it by reading "Building an API Product." The book targets Product Managers and non-technical people who want to know what it takes to build API products. If this isn’t the book for you, perhaps someone you know would like to learn from it. Share it with your contacts and help us spread the word. Get a copy of the book now! This week, I found a few interesting API-related news items related to Programmatic Ecosystems, Embedded AI, and Native Infrastructure. Let’s dive in. The developer infrastructure market experienced a massive realignment as Anthropic acquired Stainless for an estimated $300 million to upgrade how AI agents interact with the internet. Stainless is renowned for its automated tooling that ingests standard API specifications and outputs production-ready, language-native SDKs, MCP servers, and CLIs. Simultaneously, major cybersecurity and compliance vendors announced native integrations with Anthropic’s Claude Compliance API. The list of vendors includes Geordie (news), Evo by Snyk, Varonis (news), Tenable (news), CrowdStrike (news), Netskope (news), Cribl Stream (news), Wiz (news), and Proofpoint (news). By establishing this direct connection, enterprise IT and security teams can pull AI telemetry straight into existing security stacks. The intersection of AI and software validation saw a breakthrough with SmartBear delivering its new AI Test Generation Capability for ReadyAPI, a unified quality platform designed to accelerate functional testing by up to 80 percent. This milestone addresses a major imbalance in modern DevOps, where AI-assisted coding tools have accelerated development velocity tenfold but have left traditional QA testing behind, resulting in accumulated testing debt. Turning to the funding landscape, loyalty platform startup Benji secured $6.25 million in seed funding led by Preface Ventures and Atinc to expand its engineering and go-to-market teams in New York and Chicago as it builds out a universal loyalty partnership API. This unified API acts as a centralized connective tissue that reduces cross-brand reward integration deployment timelines from months to days. In a similar push toward financial simplification, stablecoin infrastructure startup Checker secured $8 million in Pre-Seed and Seed funding led by Galaxy Ventures, Al Mada Ventures, and Framework Ventures to expand its digital asset payment solutions across emerging markets. Checker offers a unified, institutional-grade orchestration layer via a single API that eliminates the need for banks, remittance firms, and neobanks to manually stitch together disjointed blockchain infrastructure. Meanwhile, Estonia-based AI writing technology company Aithor launched its business-focused Humanizer API to help content teams, publishers, and e-commerce brands seamlessly integrate text-humanization capabilities directly into internal workflows. By moving this technology off-platform and exposing it via a developer API, enterprises can programmatically bypass manual editing bottlenecks, allowing internal editorial pipelines to make direct requests to Aithor’s endpoints to automatically strip out predictable LLM sentence structures. In the realm of public safety and environmental health, California Governor Gavin Newsom announced a new live REST API feature for CalHeatScore, a heat-health ranking system developed by the California Environmental Protection Agency. This development transitions CalHeatScore from a static web tool into an open, programmatic data stream, feeding real-time, 7-day localized heat risk scores ranked from zero to four directly to external platforms at the ZIP-code level. CalHeatScore turns complex weather data into a simple daily number. It looks at forecasted temperatures and historical emergency room data to give every California ZIP code a score from 0 to 4. Enterprise threat defense also saw an upgrade as KnowBe4 updated its Inbound Email Security platform by launching the KnowBe4 Defend Graph API integration alongside localized, native-language security coaching. The system performs rapid, mailbox-level analysis and automated threat remediation without altering mail flow. Venturing into entirely new frontiers of data translation, pet tech startup Traini announced the official launch of the world’s first Pet Emotional Intelligence API, establishing a foundational multimodal infrastructure layer aimed at decoding non-human communication. By integrating this specialized API, veterinary clinics, pet insurance providers, and other companies can bypass the complexity of building cross-species language mapping from scratch and instead use a single API connection. Ultimately, the enterprise landscape is moving past standalone, cloud-locked software in favor of deeply interconnected, programmatic environments. Whether through platform consolidation like Anthropic’s acquisition of Stainless, specialized niche tooling like Traini’s behavioral models, or public sector data streams like California’s CalHeatScore, APIs have cemented their role as the primary circulatory system of modern technology. What will we see next week? Stay tuned! Thanks for reading The API Changelog! Subscribe now for free.

May 26, 2026

Moving Beyond OpenAPI for Agentic Experience

Forget all you learned about developer experience. The goal has changed. Now, API design is not just about helping people build integrations. Now what matters the most is making sure that AI agents have as smooth an experience as possible. Why? Because a growing percentage of API requests is not made by developers. More than that, a growing number of API integrations aren’t needed anymore. AI agents can easily access APIs on the fly, without needing a previously configured integration. But to make the most of APIs, AI agents need to have a full understanding of what they do. While humans care about reading nicely written documentation, agents are more interested in structure, semantics, and machine-readable definitions. So, how do you improve the quality of those elements? Keep reading to learn more. This article is brought to you with the help of our supporter, Scalar. Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth. Try Scalar for free! Until not long ago, it was easy to onboard API consumers just by handholding them into their first request. Time-to-first-request, or TTFR, became the golden metric for API DX. We all got used to talking about TTFRs of days or, at best, a couple of hours. And that all worked, even with less-than-ideal documentation. Usually, a few demos and support calls would solve any difficulties. Well, that doesn’t work (and doesn’t scale) where we are now. AI agents aren’t good at navigating ambiguity. They can only infer what they have to do from the information you share with them. Here are the three examples of the friction points AI agents find when they interact with an API: Semantic Ambiguity: Sometimes the name or structure of an operation can be interpreted in more than one way, even if it seems obvious to the person who designed it. An AI agent doesn’t have that human experience to fill in the blanks. Without explicit definitions, the agent has to guess what the operation actually does, which often leads to integration errors and broken workflows. Fragile Error Handling: When an API fails, a developer manually writes a retry loop or handles rate limits. An AI agent facing a generic 400 Bad Request or an HTML error page is blind. It has no programmatic way to determine if an error is transient, permanent, or how long to back off before trying again. Interactive Security Obstacles: Redirection-heavy OAuth 2.0 authorization flows, session cookies, and interactive CAPTCHAs are built to stop bots. But they also render APIs completely inaccessible to autonomous agents that need to authenticate programmatically. These are just three examples of factors that can contribute to a poor agentic experience, or AX. The more difficulties an agent has in interacting with an API, the worse the results will be. Solving this problem is possible, though. Designing for AX doesn’t mean you have to throw away your existing APIs. Your API definitions and documentation aren’t just reference material, though. They’re structured runtime contexts for AI agents. With those resources, you can help AI agents navigate your API reliably and safely. So, how do you make your API ready for AI agentic consumption? Well, an AX-optimized API needs to have a few qualities. First, it has to be highly semantic so that any AI agent can understand what each operation does without doubt. To get there, use precise resource naming, descriptive metadata on every operation, parameter, and attribute, and explicit parameter constraints. With that in mind, the API definition becomes a deterministic contract that AI agents will follow. But that’s not enough. It should also explicitly declare real-world side effects to help AI agents know if an operation can be potentially destructive. You can do that with the help of the MCP tool annotations that you can add to your OpenAPI document. To add it, create the x-mcp-annotations object inside any operation. Then populate it with a combination of the readOnlyHint, descructiveHint, and openWorldHint, just to name a few options. The next step is improving all error messages by providing responses with machine-interpretable recovery instructions, with the help of RFC 9457. Finally, you should indicate which level of trust AI agents need to access your API. You can do that using the OpenAPI x-agent-trust extension and specifying one of the existing trust levels that go from L0-UNTRUSTED up to L4-FULL. This information tells agents how they can authenticate themselves and what the minimum level of trust is. In essence, the goal is to tell agents in a machine-readable way what they can or can’t do with your API. All the solutions I just shared are really interesting. However, they’re quite new and are prone to evolving rapidly, so keep that in mind. Also, pay attention to a few difficulties you might find along the way. One of the things you’ll notice is that documentation can no longer be a secondary priority. Whatever you deploy to production needs to be properly documented. Otherwise, AI agents won’t be able to use your API to its full extent. Speaking about the full extent, something else to keep in mind is the potential increase in costs due to adding more information to prompts. The more information you add to your OpenAPI document, the more tokens you’ll spend. That happens because the full API definition needs to be injected into the model’s context window. The final difficulty has to do with security. To avoid having AI agents use your API in destructive ways, you need to invest in fine-grained authorization and rate limiting. Otherwise, you risk having unauthorized access or even denial of service. Are you convinced yet? It’s undeniable that the main API consumers are increasingly AI agents. However, it’s also undeniable that the costs of improving AX aren’t negligible. At this point, you can choose to stick with traditional, human-only DX. You keep maintaining standard API documentation and hoping the next generation of AI agents is smart enough to guess their way through your ambiguous endpoints. Or, you can make an investment now and adapt what you have to welcome AI agents as API consumers. I know what I’d do if I were you. Thanks for reading The API Changelog! Subscribe for free to receive new posts and support our work.

May 22, 2026

FedNow API, GhostLock, Everlaw Legal Holds

This is issue 2026.20 of the API Changelog, a mix of API news, commentary, and opinion. In this issue, you'll get to know the most relevant API-related information from the week of May 11, 2026. Subscribe now, so you never miss an issue of the API Changelog. What are the steps to create a successful API product? Learn about it by reading "Building an API Product." The book targets Product Managers and non-technical people who want to know what it takes to build API products. If this isn’t the book for you, perhaps someone you know would like to learn from it. Share it with your contacts and help us spread the word. Get a copy of the book now! Whoa, what a week! API infrastructure is changing fast. It now connects advanced AI systems, automated company workflows, and the secure infrastructure that supports everything. Let’s look at some of the things that have been grabbing my attention. F5 has expanded its strategic collaboration with Red Hat to deliver native protection mechanisms inside Red Hat OpenShift. This partnership directly targets the growing threat of unmanaged shadow APIs and the overall complexity of modern Kubernetes deployments. Researcher Kim Dvash recently introduced GhostLock, a Python-based proof-of-concept tool that demonstrates how low-privileged users can orchestrate a widespread Denial of Service (DoS) across file-share networks without altering or encrypting data. The utility exploits a documented, native Windows Win32 file API function known as CreateFileW. By explicitly passing the sharing mode parameter dwShareMode = 0x00000000, the tool requests an exclusive deny-share handle over targeted files across SMB network shares. GhostLock can completely bypass detection because it doesn’t use any writes or encryption. Instead, it looks like a simple file indexer. When scaled across entire directory structures, it blocks access for all other network clients, inducing continuous STATUS_SHARING_VIOLATION errors. Analysts point out that this is an abuse of legitimate data-integrity API parameters rather than a system flaw, meaning the access restriction is instantly removed as soon as the offending SMB session holding the API handles is terminated. In the fintech space, the Uniswap API has rolled out a major architectural upgrade that native developers can use to support direct payment flows for decentralized applications. Historically, multi-asset routing required developers to write custom smart contracts or guide users through manual, multi-step operations to swap a token and send the final output to a third-party recipient. The updated Uniswap API natively handles this by allowing developers to embed a designated recipient address parameter straight into their programmatic quote requests. Uniswap is an automated market maker (AMM) or a set of smart contracts that let anyone swap tokens, provide liquidity, or create new markets directly on-chain. Further expanding the capabilities of Web3 infrastructure, Bitget Wallet has officially launched its self-service B2B API Portal to programmatically scale on-chain trading for developers and institutional clients. Built on Bitget’s proprietary DEX aggregation engine, which actively routes over $20 million in daily trading volume, the platform eliminates the need to build background liquidity networks from scratch. The newly exposed suite of developer endpoints includes a Trading API for optimal asset pricing, a Cross-chain API for unified multi-network swaps, and a Market Data API covering 33 public networks and over 200 tokenized stocks. The portal now supports new ecosystems like HyperEVM and Hypercore to help decentralized systems scale. It adds fast blockchain queries and interfaces to broadcast transactions. At the same time, specialized data pipelines are redefining consumer intelligence and fraud prevention through real-time endpoint capabilities. Homesage.ai has entered the PropTech market with a high-accuracy, RESTful Skip Tracing API designed to deliver structured U.S. property owner records to real estate platforms, lenders, and wholesalers. This API uses JSON schemas and standard JWT authentication. It lets third-party tools like CRMs make fast requests to find phone numbers, email addresses, and confidence metrics. The performance is under 100ms, and there is no need to manage a complex data infrastructure. In a similar vein, the Federal Reserve Financial Services has rolled out its FedNow Service network intelligence API to fight authorized push-payment fraud and transaction anomalies actively. This RESTful API runs independently of the main payment system. It lets banks use the FedLine Developer network to check receiver history and behavior before approving an instant payment. Automated compliance systems can then block or flag suspicious transfers immediately. A FedNow payments flow involves five key parties: the payer, the payer’s bank, the FedNow network, the payee, and the payee’s bank.—ACI Worldwide The evolution of API technology is also fundamentally altering how humans and machines interact with complex technical documentation. Perfect Corp. has addressed integration barriers by deploying an interactive “Ask AI” assistant directly within its YouCam API developer portal. This conversational assistant helps developers adopt augmented reality and beauty tech tools. It reads dense API documentation in real time to deliver local implementation strategies, parameter guides, and debugging code. It also translates complex schemas into plain business logic for other teams. Brivo is re-engineering its platforms for machine-to-machine comprehension by launching an AI-friendly iteration of its Security Platform API. By incorporating video endpoints from Eagle Eye Networks and structuring documentation with markdown-optimized maps like llms.txt, Brivo has built an architecture engineered specifically for LLMs and Agentic AI tools. Finally, commercial scaling and foundational developer initiatives are reshaping how decentralized applications function without heavy dependence on cloud monopolies. Medical Care Technologies Inc. (MDCE) has announced an explicit shift toward a B2B SaaS commercialization strategy by launching its Enterprise Vision API. This interface serves as a programmable gateway for third-party platforms to programmatically consume computer vision intelligence for workflows like factory quality control and agricultural monitoring without building local machine learning layers. Tether is launching an open-source movement away from centralized web APIs through its Developer Grants Program. Tether is offering rewards up to $4,000 to motivate developers to build local-first applications. By using its QVAC platform and Wallet Development Kit, applications run AI inference and financial actions on-device. This limits reliance on remote cloud APIs, minimizing privacy risks and fees. Everlaw has expanded its legal document preservation capabilities by introducing a dedicated Legal Holds API. This endpoint exposes real-time litigation hold data, custodian lists, and compliance metrics to internal IT environments. It lets developer teams feed live preservation metrics directly into corporate dashboards. It also triggers workflows automatically across external platforms like Slack or Google Vault. This replaces manual exports with seamless data automation. The growth of specialized endpoints shows that modern software depends on automated API architectures. APIs are no longer simple connectors. They are the framework driving innovation by securing AI, enabling local-first systems, and connecting business pipelines. As automated tools begin writing their own integration logic, success will belong to organizations that prioritize clear documentation, built-in security, and interoperability. Until next week! Thanks for reading The API Changelog! Subscribe now for free.

May 19, 2026

Moving from API Operations to Business Capabilities

How to organize your API operations into business assets.

May 15, 20261 likes

Traefik Labs Ingress NGINX Migration, Solana Pay.sh, Akamai Security Posture

The API Changelog issue 2026.19

May 12, 20261 likes

IBM Envizi, Redpine €6.8M, Command Zero Programmatic Security Investigation API

The API Changelog issue 2026.18

May 5, 20261 likes

Putting the Brake on Autonomous API Workflows

Why the most sophisticated workflows still need a human-in-the-loop to succeed.

May 1, 2026