Governed API integration for AI agents: contracts, mappings and confirmed writes

The agent ordered 400 units. The ERP booked 400 cases.

A procurement agent handles a request to restock safety gloves. It finds the approved supplier, checks the budget and calls a "create purchase order" tool. The tool is a thin wrapper around the ERP's API: the agent fills in a JSON object, and the wrapper forwards it.

The agent sends a quantity of 400. It doesn't send a unit of measure, because the tool description never mentioned one. The ERP fills the gap with the item's default unit: cases of 12. The order is for 4,800 gloves.

The ERP replies 202 Accepted. The agent reports "Purchase order created" and closes the task. In fact the order is queued for credit review, because the total now exceeds the supplier's limit. It's never released. The gloves that were actually needed don't arrive, and nobody knows why for two weeks.

Nothing threw an error. The agent formed a valid request. The wrapper forwarded it faithfully. The ERP applied its documented default and its documented credit rule. The failure lived in the space between them: an implicit mapping, a silent default and an unconfirmed write.

What is a governed API client?

A governed API client is a versioned connection to one API operation with an explicit contract: typed inputs and outputs, a declared field mapping, defined error meanings, required authority and a rule for confirming success. The agent proposes values; the client validates, maps and executes them.

The difference from a free-form tool call is where the knowledge lives. In a free-form call, the model has to infer from a description which fields matter, what units apply and what a response means. In a governed client, those facts are written down once, reviewed, versioned and enforced on every call.

Why do free-form tool calls fail against enterprise APIs?

Because enterprise APIs are full of implicit meaning (units, defaults, partial updates, async processing) that a model can't reliably infer from a tool description, and a forwarding wrapper doesn't check. The request succeeds technically and fails in business terms.

Enterprise APIs are built for integrations written by developers who read the documentation and test edge cases. Agents read a short description and fill in what seems reasonable. Common gaps:

• Optional fields with consequential defaults: unit, currency, timezone, tax code, warehouse.
• Partial-update semantics: a null or empty value can clear a field instead of leaving it alone.
• Asynchronous processing: 202 Accepted means the request was queued, not completed.
• Overloaded fields: a "status" or "type" field that changes downstream behavior.
• Writable properties the caller shouldn't touch: OWASP's API Security Top 10 lists broken property-level authorization, including mass assignment, where a client sets fields it was never meant to.

A wrapper that forwards whatever JSON the model produces exposes the agent to every one of these. OWASP's agentic list names tool misuse among the top risks for exactly this reason: the tool works as built, and the agent uses it in ways nobody intended.

What an API client should declare

An OpenAPI document describes an API's shape, and JSON Schema validates payloads. Both are essential inputs. Neither says how your business meaning maps to the API, or what to do when the response is ambiguous. A governed client adds that:

Where do silent errors come from in API mappings?

From the values nobody sent: target-side defaults, nulls that clear fields, unmapped enums and unit or timezone assumptions, all of which the API accepts without complaint. Silent errors are dangerous precisely because every layer reports success.

Who holds the API credentials?

The runtime does, never the agent: credentials are attached at call time, scoped to the operation, and the call runs within the authority of the person the agent acts for. A key the agent can see is a key it can leak, misuse or carry into the wrong task.

Putting an API key in a prompt, a tool config the model reads, or an environment the agent can query creates three problems. The key can leak through output, logs or prompt injection. The agent can use it for calls nobody approved. And the key usually carries the integration's broad service authority, not the narrower authority of the person who asked for the work.

A governed client fixes all three. Credentials are stored once, outside any agent's reach. The runtime attaches them when a validated call executes. Before that, it checks that the person the agent acts for may perform this operation on this record for this purpose. OWASP's API list puts broken authentication and broken function-level authorization near the top; the agentic list adds identity and privilege abuse. The answer to all of them is the same: authority is decided by the runtime, per call, not carried around by the agent. More on delegated authority in AI agent identity.

Is a 200 or 202 response a confirmed result?

Not necessarily. A 202 means the request was accepted for processing, not completed, and even a 200 may describe a record that's pending review, partially applied or later rejected. Carry each write through to a result the system of record confirms.

RFC 9110 is explicit that 202 Accepted means processing hasn't finished and may still fail. Many enterprise APIs also return success for records that land in a draft, held or pending state. In the opening scenario, "accepted" turned into "held for credit review" and stayed there.

For each write, the client declares what confirmation looks like:

1. Read back the created or updated record and compare it to what was authorized.
2. Poll status for asynchronous operations until a terminal state, with a deadline.
3. Match a callback or event to the original operation.
4. Treat a timeout as unresolved, not failed: query the target before any retry.

Only then does the workflow mark the action complete. If the confirmed record differs from what was authorized (a different unit, amount or status), that's a typed outcome with its own route: correct, escalate or reverse as a new governed action. Timeouts and retries are covered in depth in retries and idempotency.

Treat API responses as data, never instructions

Responses flow back into the agent's context, and that's a second attack surface. OWASP's API list includes unsafe consumption of APIs: trusting third-party responses without validation. For agents the risk is sharper, because a free-text field in a response can carry instructions the model may follow.

Validate responses against the declared output contract. Pass the agent typed fields it needs, not whole raw payloads. Map errors to typed outcomes (RFC 9457 problem details make that easier when the API supports them) so the workflow branches on cause instead of the model interpreting an error string.

When the contract changes, compare versions

APIs change, and so do mappings. A field is renamed. A new required field appears. An enum gains a value. A default changes on the target side. A mapping is edited to fix one workflow and breaks another.

Treat a client like any other published dependency. Compare the old and new contract and mapping side by side, see which workflows use it, test against recorded cases, and require approval before the new version goes live. Paused work stays bound to the version it started with until it's safe to move. For the general pattern, see typed contracts for AI workflows.

Common anti-patterns

Ten rules for governed API integration

1. Give each business operation its own governed client.
2. Declare the input and output contract, including units and ranges.
3. Map every field explicitly; never set fields outside the mapping.
4. Allow no silent defaults: required, mapped or reviewed.
5. Keep credentials in the runtime, never in the agent's view.
6. Check the acting person's authority on every call.
7. Treat accepted as pending and a timeout as unresolved.
8. Confirm each write against the system of record.
9. Validate responses and pass the agent typed fields only.
10. Version contracts and mappings, and compare before publishing.

The result: agents that change systems the way you intended

Agents become useful when they can act on real systems, and dangerous when those actions rest on guesses. Governed API clients move the guessing out of the model and into reviewed, versioned contracts: what fields mean, which defaults apply, who may call what and what counts as done.

The agent still proposes. The runtime validates, maps, authorizes, executes and confirms. When something goes wrong, you can see which contract version ran, which values were mapped from where and what the system of record actually recorded. That's the difference between an integration that works in a demo and one you can let run.