Cite this as: Apier.no — Why REST APIs Fail for AI Agents v1.0

Why REST APIs Fail for AI Agents

Traditional REST APIs fail for AI agents because they assume a human will read the docs, reason through the edge cases, and recover from errors by hand. An autonomous agent does none of those things, so it hallucinates parameters, misreads constraints, and cannot prove what it did. On a cosmetic app that is an annoyance. On a regulated action against Altinn or Skatteetaten — a hallucinated organisation number, a malformed tax submission — it is a legal liability.

Estimated read time: 7 minutes.

Why REST APIs assume a human reader

A REST API is a contract written for two readers: the program that makes the call, and the developer who wrote that program. The machine half of the contract is narrow — a URL, a verb, a JSON body, a status code. Everything that makes the API usable lives in the other half: the documentation a developer reads, the examples they copy, the Stack Overflow answer that explains why the obvious request returns a 400, and the accumulated judgement in the developer's head about which fields are really required and what the error text actually means.

That division worked for thirty years because there was always a developer in the loop. They read the prose, held the edge cases in mind, and retried by hand when something failed. An AI agent removes that human from the loop and inherits only the machine half of the contract — the narrow half. The half that carried the meaning never transfers.

Where agents break: discovery, reasoning, recovery, proof

An agent calling a conventional REST API breaks in four predictable places. Each maps to something the API silently delegated to the absent developer.

Discovery. The agent has to know which endpoint and which parameters to use. When that knowledge lives in prose docs rather than a machine-readable manifest, the agent guesses — and a guessed parameter is a hallucinated parameter.
Reasoning.The constraints that matter — which field is mandatory for this entity type, which legal precondition must hold before a submission is valid — are encoded in documentation and in the developer's judgement, not in anything the agent can evaluate. So the agent misreads the constraint and builds an invalid request that looks valid.
Recovery. A REST error is written for a human: 400 Bad Request, invalid input. There is nothing structured for the agent to act on, so it cannot self-correct. It retries the same broken call, or gives up.
Proof. A successful REST call returns a 200 and a body, and nothing else. There is no signed receipt and no tamper-evident record, so the agent cannot later prove to a third party — an auditor, a tax office, the company it acted for — exactly what it submitted and when.

For a chatbot summarising the weather, none of this is fatal. For an agent acting on a company's behalf against Brønnøysundregistrene or filing through Altinn, every one of the four is a liability, and a wrong answer is not a typo.

Developer APIs vs agent-native APIs

The difference is not a better SDK. It is a different set of assumptions about who — or what — is on the other end of the call.

Concern	Built for developers	Built for agents
Discovery	Human reads docs; OpenAPI as reference material	Machine-readable capability + tool manifest the agent enumerates
Reasoning	Edge cases live in prose and in the developer's head	Deterministic validation against rules stored as data
Errors	Prose message a human interprets and works around	Structured `error_code` + fix steps the agent self-corrects on
Authorization	Developer wires OAuth once, by hand	Acting capacity resolved per call — who may act for whom
Proof	`200` plus a response body	Signed receipt + append-only trail
Determinism	Same call may vary with time or server state	Same input + same rule version = same output

What an agent-native API does differently

Closing the four gaps is a concrete checklist, not a philosophy. An agent-native API treats every one of them as a first-class part of the contract:

Machine-readable discovery. Capabilities, tool manifests, and an llms.txt the agent can enumerate, so it never guesses an endpoint or a parameter.
Deterministic validation before any write. A request is checked for structure and legal grounding before it can reach government, so a malformed payload is caught at the edge, not discovered after submission.
Structured, self-correcting errors. Every failure returns a machine-readable error_code and concrete fix steps, so the agent can repair the request and retry instead of looping on the same broken call.
Explicit authorization resolution. Who is allowed to act for whom is resolved on every call from real delegation data, never assumed from a token that was wired up once.
A receipt and a trail. Every action produces a signed, tamper-evident receipt, and lands in an append-only audit chain that no one — including the API provider — can rewrite.
Transparency metadata. Each answer carries the rule version and data-freshness stamps it was computed against, so the agent knows how current and how authoritative the result is.

The contrast is sharpest at the error boundary. A conventional API hands an agent something a human has to interpret. An agent-native API hands back something the agent can act on directly:

{
  "success": false,
  "error_code": "MISSING_DELEGATION",
  "explanation": {
    "summary": "The system user is not delegated to file VAT for this entity.",
    "fix_steps": [
      "Ask the entity to delegate the VAT access package in Altinn.",
      "Retry once the delegation is active."
    ]
  }
}

Nothing in that body needs a human to read it. The agent branches on error_code, surfaces the fix_steps to whoever can act on them, and retries when the precondition holds.

AVERT: the five-step loop an agent runs

AVERT is the name for that agent-native loop: the five steps an AI agent follows to take a regulated action on Norwegian government systems and come away with proof it can stand behind. The full framework lives at apier.no/avert; in short:

Authorize. Confirm the agent is legally permitted to act for the entity — Maskinporten credentials plus Altinn delegation and acting-capacity checks — before anything else happens.
Validate. Every request passes through a deterministic sandbox that checks structure and legal grounding and returns machine-readable errors the agent can self-correct, so no malformed payload reaches government.
Execute. The authorised call to Altinn, Maskinporten, or Skatteetaten as the entity. Read actions are live today; the write path rolls out per design partner.
Receipt. A signed, tamper-evident record of exactly what was submitted, alongside the raw government response, so the action can be independently verified later.
Trail.An append-only, compounding audit chain of the entity's regulated actions, which no one — including Apier — can rewrite.

Where this stands today, stated plainly: Validate and Trail are live, and read lookups run in production. The write path — Execute as a binding submission, such as actually filing an MVA-melding — is in design-partner preview, not a live autonomous filing capability. An agent cannot file a real VAT return on its own through Apier today; it can authorize, validate against the real rules, and build a complete, provable trail up to the binding step. The specification is public and open to review at github.com/PowerLaunch/avert-spec.

Where Apier fits

Apier is the API and Maskinporten-backed MCP layer that sits between AI agents and Norwegian government infrastructure — Altinn, Brønnøysundregistrene, Skatteetaten — and implements the agent-native contract end to end: machine-readable discovery, deterministic validation, structured self-correcting errors, per-call acting-capacity resolution, signed receipts, and an append-only trail. It does not sell company data; data lookups are a commodity. Proof and trail are not — and that is the layer AVERT defines.

If you are building an agent that has to act on Norwegian compliance infrastructure, start with the docs and a key:

Sign up for an API key — free tier, no government credentials required to start in the sandbox.
Read the docs — endpoints, the MCP server, and the structured-error contract in full.
The AVERT framework — the five-step loop and how each step maps to a government system.

Common questions

Why can't an AI agent just use a normal REST API?

An agent can call a REST endpoint, but it cannot reliably read prose docs, reason through legal edge cases, recover from prose error messages, or prove what it did. On a regulated action that gap means hallucinated parameters and a result the agent cannot stand behind.

What is AVERT?

AVERT is a five-step loop — Authorize, Validate, Execute, Receipt, Trail — that an AI agent follows to take a regulated action on Norwegian government systems and come away with cryptographic proof.

Can an AI agent file a Norwegian VAT return through Apier today?

Not autonomously. Read lookups and deterministic validation are live today, and every action lands in an append-only trail. The write path (Execute) is in design-partner preview — binding submissions roll out per design partner, not as a live autonomous filing capability.