The Agent eXperience Protocol (AXP)

Publisher: apis.ax (the standards body) · Verifier: api.qa (independent)

This document is the normative text of AXP — the Agent eXperience Protocol: the set of technical surfaces an agent-first API MUST enforce — the wire contract it publishes so that an autonomous agent can discover it, understand it, and transact with it zero-shot, on first contact, with no human reading docs in the loop. apis.ax publishes this standard; api.qa verifies conformance to it from outside the building fleet's write access.

The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as described in RFC 2119.

This specification is itself linked data: its $id (https://apis.ax/axp) is the resolver-addressable identity of the standard, $type: Spec, in the https://schema.org.ai context. Every clause below names (a) the normative requirement, (b) how it is machine-verified by an independent api.qa check or pinned requirement, and (c) why an agent needs it.

Clause 1 — OpenAPI 3.1 contract

Normative. A conforming API MUST publish a valid OpenAPI 3.1 document describing every operation an agent may call, its parameters, and its typed responses. The document MUST parse and MUST declare at least one operation. The contract SHOULD be discoverable at /openapi.json or linked from the capability card.

Machine-verified by: api.qa check openapi and pinned requirement openapi-valid (surface openapi, must: valid). api.qa fetches the document, parses it, and confirms it is a structurally valid OpenAPI 3.1 contract with enumerable paths.

Why an agent needs it: the OpenAPI 3.1 contract is the machine-readable shape of the API. Without it an agent must guess call signatures; with it the agent binds to the surface deterministically and calls correctly on the first try.

Clause 2 — llms.txt

Normative. A conforming API MUST serve an llms.txt file at /llms.txt: markdown, with an H1 title and substantive, agent-actionable content that orients a language model to what the surface is and how to use it. It MUST NOT be an HTML page. It SHOULD cross-reference the sibling machine surfaces (agents.json, icp.json, the OpenAPI 3.1 contract).

Machine-verified by: api.qa check llms-txt and pinned requirement llms-present (surface llms.txt). api.qa confirms /llms.txt returns markdown (H1 + substantive body), not markup.

Why an agent needs it: llms.txt is the plain-language front door for a model — the one file a fresh agent reads to learn the surface without scraping a rendered site.

Clause 3 — markdown-first content negotiation

Normative. A conforming API MUST content-negotiate its resolver-addressable home and its typed bodies markdown-first: a request with Accept: */* (an agent/curl) MUST receive machine-legible markdown or JSON, never a wall of HTML; a request with Accept: text/html (a browser) MAY receive HTML. Human presentation MUST NOT be the only representation. Typed bodies MUST be markdown-first — the agent representation is primary, the human rendering is derived.

Machine-verified by: api.qa check content-negotiation, pinned as its own requirement check-content-negotiation (kind: check, must: pass) — the clause binds to this discriminating check directly, not to the coarse AX floor (a target that serves HTML to Accept: */* fails this MUST even if it would otherwise clear the floor). api.qa fetches the home twice with differing Accept headers and confirms the agent representation is non-HTML while the browser representation is HTML.

Why an agent needs it: markdown-first negotiation means an agent extracts meaning directly from the response instead of parsing a DOM built for eyes.

Clause 4 — typed BLOCKED/EMPTY errors that never fake success

Normative. A conforming API MUST return typed outcomes for the no-result and not-permitted paths and MUST NOT fake success. An empty result set MUST carry an explicit EMPTY type (not a bare 200 with an empty array masquerading as data); a forbidden or gated request MUST carry an explicit BLOCKED type with a non-2xx status. A conforming API MUST NOT return a 200 success envelope when the true outcome is BLOCKED/EMPTY.

Machine-verified by: api.qa check claims-honesty and pinned requirements typed-empty-not-faked and typed-blocked. api.qa probes a known-empty query and a known-forbidden query and confirms each response is the correctly typed EMPTY / BLOCKED body — a faked 200 fails the contract.

Why an agent needs it: an agent acts on outcomes. A faked success sends the agent down a wrong branch silently; a typed BLOCKED/EMPTY lets it re-plan, escalate, or pay — deterministically.

Clause 5 — hard-ceiling metered pricing

Normative. A conforming API that meters usage MUST expose its pricing as machine-readable metered pricing with a hard-ceiling: a declared maximum spend, strictly greater than zero, the caller cannot exceed without an explicit new authorization. Payment boundaries MUST answer as structured offers (HTTP 402 with an offer body carrying id/title and price), and the metered price MUST publish the hard-ceiling so an agent wallet knows its worst-case exposure before it calls. A request that would exceed the declared ceiling MUST be stopped with a re-authorization boundary (HTTP 402), never silently metered past the cap.

Machine-verified by: api.qa check offers-402, pinned as its own requirement check-offers-402 (kind: check, must: pass), plus pinned endpoint requirements hard-ceiling-pricing (the pricing surface reports a metered model with hardCeiling > 0) and hard-ceiling-enforced (a probe that exceeds the declared ceiling is answered with a 402 re-authorization boundary, not a silent 200). api.qa probes the declared payment boundary for a structured 402 offer, reads the metered ceiling, and behaviorally verifies the ceiling is enforced.

Why an agent needs it: an autonomous wallet cannot spend safely against an open-ended meter. A hard-ceiling makes worst-case cost knowable and bounded, so the agent can commit funds without a human approving each call.

Clause 6 — resolver-addressable home

Normative. A conforming API MUST have a resolver-addressable home: a stable, resolvable canonical identity (a capability card at /.well-known/agents.json and a resolvable root) that an agent can address, resolve, and cross-link from the sibling surfaces. The home MUST resolve to a valid capability card naming the surface and its interfaces.

Machine-verified by: api.qa check agents-json, pinned as its own requirement check-agents-json (kind: check, must: pass), plus the surface requirement agents-present (surface agents.json, must: valid). api.qa resolves the capability card and confirms it names the surface and its interfaces, and that the surfaces cross-reference each other — the clause binds to the discriminating agents-json check, not the coarse AX floor.

Why an agent needs it: the resolver-addressable home is the single address an agent resolves to find everything else. Without it the surface is an island an agent cannot reliably re-find or link.

Clause 7 — keyless first value

Normative. A conforming API MUST deliver its first unit of real value with no API key, no signup, and no account: at least one declared, discoverable endpoint MUST answer 2xx with substantive typed content to an anonymous agent on first contact. Authentication and payment MAY gate deeper or metered use, but the surface MUST NOT require an account before an agent can obtain any value at all.

Machine-verified by: api.qa check keyless-flow, pinned as its own requirement check-keyless-flow (kind: check, must: pass), plus the pinned endpoint requirement keyless-first-value (a declared endpoint answers 2xx with no credential). api.qa samples the endpoints declared by agents.json and the OpenAPI contract and confirms at least one answers 2xx keyless.

Why an agent needs it: a fresh agent cannot negotiate an account before it knows whether the surface is useful. Keyless first value is what lets it integrate zero-shot on first contact — the whole point of the agent-first web.

Conformance

Conformance is verified by api.qa, held outside the building fleet's write access (verifier independence); a Listing is admitted to the apis.ax catalog iff it passes this standard's conformance profile.

The mapping from each clause above to its independent api.qa verification is published, machine-readable, at [conformance/profile.json](./conformance/profile.json). The conformance profile is executable as an api.qa PinnedSpec at [conformance/apis-ax-standard.spec.json](./conformance/apis-ax-standard.spec.json): the apis.ax curation gate expressed as a machine-checkable contract. A target passes iff api.qa returns passed: true against that pinned spec — the standards body publishes the bar, the independent verifier decides whether it is cleared, and the building fleet can edit neither verdict.

Because the verifier is held outside the fleet that builds the catalog, a Listing cannot grade itself: the gate is mechanical, not aspirational, and that independence is the whole point.