The gap between what an API exposes and what an AI needs to know
There is a precise technical reason why connecting an LLM to your APIs is not sufficient for production AI operations. It is not about model capability. It is about what an API is — and what it is not.
An API is a capability surface. It exposes what a system can do. The endpoint exists. The method accepts these parameters. The response returns this shape.
What an API does not contain: how those capabilities must be used. The sequence that must be followed. The states that preclude certain operations. The roles that cannot reach certain methods. The conditions under which a technically valid call is operationally wrong.
That knowledge exists. It governs every action your engineering team takes when they interact with your systems. It is just not encoded anywhere a machine can read.
Why prompts do not close this gap
The standard answer is to put the rules in the system prompt. Tell the model what it should and should not do.
This works until it doesn't — and in production, it eventually doesn't.
A prompt is advisory. The model reads it at the start of a session and applies it probabilistically across the turns that follow. Attention drifts. Context shifts. The model that correctly followed your rules on turn three may not follow them on turn seven — not because the rules changed, but because each inference pass is an independent reasoning act. The rule was never compiled into the execution. It was re-applied, each time, by discretion.
For governed execution of real systems, discretionary rule-following is not sufficient. You need something structural.
What a domain contract is
A domain contract is a typed, versioned specification of how a capability group in your system works — not just the method signatures, but the operational model.
It encodes:
- Entity lifecycle — what states exist, what transitions are permitted, what transitions are forbidden regardless of how the request is framed
- Hard boundaries — operations that must never execute, stated explicitly, not inferred
- Business rules — the conditions that govern correct execution in this domain
- Access constraints — what a caller at this permission level can and cannot do
Here is what one looks like for an orders domain:
/**
* SYSTEM CONTEXT
* Orders follow a five-state lifecycle: pending → confirmed → picking
* → packed → dispatched → delivered. Transitions are one-directional.
* Cancellation is only permitted in pending or confirmed states.
*
* HARD BOUNDARIES
* Never cancel an order in picking, packed, or dispatched state.
* Never call list() to find a single record — always use getById().
* Never advance order status without a confirmed task assignment.
*
* BUSINESS RULES
* Orders above ₹50,000 require explicit confirmation before dispatch.
* Customer tier affects pricing — always fetch current tier before quoting.
*/
interface OrdersAPI {
getById(params: { orderId: string }): Promise<Order>;
confirm(params: { orderId: string }): Promise<{ status: string }>;
cancel(params: { orderId: string; reason: string }): Promise<{ status: string }>;
}
This is not a prompt. It is not a knowledge base entry. It is a versioned, typed specification loaded at startup and present on every session. The agent reads this contract before it touches any operation in this domain.
What changes when the agent reasons inside a contract
The difference is where the rule enforcement happens.
With a prompt: the agent reasons about what to do, executes it, and the rules are applied — or not — during that reasoning.
With a domain contract: the agent reasons inside a typed model of the domain. Before it writes a single line of execution code, it has read that cancelling a dispatched order is forbidden. That knowledge is not a suggestion it can reason around. It is structurally present in the specification it is working from.
A forbidden operation does not get attempted because the agent knows — from the contract it reasoned inside — that the operation is forbidden. The enforcement happens at the reasoning layer, before execution.
This is the difference between advisory governance and structural governance. Both are real. Only one is sufficient for production systems where a wrong action has consequences.
One further property worth naming
A domain contract captures the relationships between capabilities, not just the capabilities themselves.
The order contract above does not just expose cancel(). It encodes that cancel() has a precondition — the order must be in a permitted state — and that violating it is a hard boundary, not a soft preference. The agent that reads this contract understands the operation in its operational context, not just its technical signature.
This is closer to how a senior engineer understands a system than to how an API client understands it. The senior engineer knows what the endpoint does and when it should and should not be called. The API client knows only the former.
Domain contracts give the agent the second kind of knowledge — the kind that makes the difference between an agent that can call your systems and an agent that can operate them correctly.
Where this leads
The domain knowledge problem is the engineering reason most enterprise AI deployments are scoped conservatively. The AI has access. It does not have the operational model that would make that access trustworthy.
Domain contracts are the primitive that fills that gap. They are not a prompt engineering technique. They are infrastructure — versioned, typed, compiled into the execution layer, governing every session.
This is the foundation Nexus is built on.
Nexus is a toolsystem agent (powered by Claude) — an AI whose job is to operate your systems correctly, on behalf of other AIs. Built on dataBridges and APIFront.
Nexus is a toolsystem agent (powered by Claude) — an AI whose job is to operate your systems correctly, on behalf of other AIs. Built on dataBridges and APIFront. If you want to see this demonstrated against real systems, start a conversation about a first POC.
Talk to us →