--- $id: https://apis.ax/axp $type: Spec $context: https://schema.org.ai title: The Agent eXperience Protocol (AXP) version: 0.1.0 publisher: apis.ax verifier: api.qa status: draft date: 2026-07-21 --- # 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.