Get in touch
AI
  • 5 min read

AI Doesn’t Like Your API. How to Fix It

From syntax to semantics. How to design APIs that AI agents can trust, by exposing intent and meaning, not just endpoints and fields.

  • Published on
    28 mei 2026
  • Written by
    Koen Williame

Introduction

For years, integration was mostly about syntactic interoperability. As long as protocols, data formats, and interface contracts lined up, you were good. If the JSON matched and the 200s rolled in, the integration was considered successful.

That worked reasonably well in a world where systems were mostly integrated through predictable flows, predefined mappings and human-designed orchestration.

Today, we’re moving toward AI and Agent-native integrations, opening up a new frontier of semantic and behavioral interoperability.

Because AI does not only need to call your API.
It needs to understand what the API does.
It needs to understand what the data means.
And it needs to understand what could happen next.

The challenge is that most APIs today were never designed for that shift.

From syntax to behavior to semantics

Let’s break down this evolution step by step.

We have largely solved this layer. REST, OpenAPI-spec, JSON, gRPC, and GraphQL give us mechanical consistency and reliable communication between systems.

This is about how an API actually behaves. What it does, when it does it, and how it reacts in different contexts. This layer is often underdocumented, misunderstood, and full of pitfalls. Think retries, eventual consistency, side effects, long running processes, idempotency, or asynchronous updates. Even for humans, this is where things get tricky.

This is where the real challenge begins. For AI to work with APIs, shared meaning becomes essential.

What is a “customer”? What does “status = active” really imply? Are “orders” historical, current, or pending?

These are no longer just data questions. They belong at the core of API design.

Why AI can’t just “figure out the behavior”

REST solves behavioral interoperability partially by agreeing on a set of conventions (operational interoperability). It gives us a common way to expose resources, use HTTP verbs and structure interactions.
But REST does not solve the business interoperability.

Power outlets are a good example of the difference between syntactic and behavioral interoperability. Just because the plug fits the socket (the contract / syntactic definition) does not mean the appliance will receive the voltage, frequency, or grounding (the behavior) it expects.
The physical connection may be correct, but the behavior may still be incompatible.

APIs have the same problem. A request may match the OpenAPI contract, authenticate correctly, and return a valid response. But that does not tell the consumer whether retries are safe, whether the operation is idempotent, whether the result is immediately consistent, whether the call triggers side effects, or which lifecycle state comes next. The plug fits. The behavior may still be incompatible.

And for AI agents, that distinction is critical. Because an agent does not just need to know how to call the API. It needs to understand what the call does in the real world.

Why AI can’t just “figure out the meaning”

Large language models can call your APIs. They can read an OpenAPI spec. But without semantic alignment, they will make assumptions. And those assumptions can be wrong.

Take something as simple as a field calle price.

  • Is it gross or net?
  • In which currency?
  • Does it include volume discounts?
  • Is it per item or per bundle?

For a human, these questions are obvious. For an AI agent, they are not.

Without explicit, machine readable definitions of what concepts actually mean, AI systems will struggle. Or worse, they will appear to succeed while operating on the wrong interpretation.

And that is the dangerous part.

The API call works.
The response is valid.
The automation continues.

But the underlying meaning may be wrong.

Semantic misalignment is not new

This is not a new problem. In aviation, standards like AIXM from Eurocontrol and FIXM from ICAO were designed to harmonize airspace and flight data. Even in such highly standardized domains, getting semantics right proved to be difficult.

What is different today is the impact.

AI agents do not just read data. They act on it. And when semantics are misaligned, the consequences are no longer theoretical. They become operational.

That is exactly why semantic clarity can no longer be treated as a nice to have. It has to become a design priority.

So what does this mean in practice?

If APIs need to become useful for AI, they need to evolve beyond technical contracts.
Here are four practical shifts.

Go beyond types and schemas. Enrich your API specifications with domain ontologies, business vocabularies, and clear concept definitions. Do not just describe structure. Make intent explicit.

Expose data in terms of business concepts rather than database fields. Align with domain specific semantic models where possible, such as FIBO in finance, HL7 FHIR in healthcare or European semantic initiatives such as the European Interoperability Framework (EIF) and SEMIC Core Vocabularies.

Move away from purely CRUD oriented interfaces. Design interactions around intent. Think in terms of actions like “reserve inventory” or “schedule pickup” instead of endpoints like “PATCH /inventory” or “POST /shipment”.

Ensure meaning is not only documented, but also interpretable by machines. Depending on the context, that could mean using JSON-LD, schema.org for linked vocabulary or W3C’s SHACL where RDF graph validation is appropriate.

Contrast: Shift left vs. Shift meaningful

In a previous post, we argued for a shift left in semantics. Bringing ontologies closer to the source and enabling semantic interoperability from the ground up. That is primarily a data discipline and remains essential.

This post adds the counterpart.

We need a semantic shift forward. One that embeds meaning directly into the interface layer, where APIs evolve from data pipes into true contracts of collaboration.

Because APIs are where systems meet.

And in an AI-native landscape, APIs are no longer just technical pipes. They become contracts of collaboration.

That is where integration architecture has a critical role to play.

It connects data, systems, behavior, workflows and business capabilities into something AI can safely interact with.

Build APIs AI Can Trust

AI-native ecosystems do not tolerate ambiguity (or at a high cost). For integration architects and API designers, that means semantics can no longer be an afterthought. It has to be a core design concern.

“

“Semantics should sit at the very core of interface design. Because if your API does not speak clearly, AI will fill in the blanks, and it might get them wrong.”

Koen Williame

That is the real challenge.

Your API may be syntactically correct.
It may be well-documented.
It may be secure, stable and performant.

And still, AI may not be able to use it safely.
Because AI does not only need endpoints.

It needs behavior.
It needs meaning.
It needs intent.
It needs context.

That is how APIs evolve from technical interfaces into AI-ready integration surfaces.

First, they become predictable.
Then they become meaningful.
Then they become intent-aware.
And eventually, they become part of a collaborative landscape where systems and agents can coordinate around shared goals.

That is where the next question begins.

If APIs need to evolve from pipes into partners, what does API maturity look like in the agentic era?

Latest articles

Read all insights

Tap into the knowledge
of our community.

Back to the knowledge hub Get in touch