Putting a door on a legacy API

The door, not the rebuild

The agentic internet does not require an organisation to rebuild its systems. Most of the services an agent needs to reach are ordinary web APIs behind ordinary websites, and the gateway layer exists to put a machine-readable door on one of them without touching what is behind it. A human sees your website; an agent fetches one file and learns who is accountable, which actions it may take, where each lives, what it costs, how to pay, and how to authenticate.

The open spec for the door is agent/1, and its companion agent-dns/1 is how an agent gets from a bare domain name to the door — one DNS record that points at the document, the way DNS once turned a name into an address. The gateway is deliberately the layer with the lowest cost of adoption, because it is the on-ramp: an organisation can join the agentic internet by publishing one file, long before it has anything else on the stack.

One file at a well-known path

The discovery document lives at a single well-known path, /.well-known/agent, with no alternate spelling. A consumer fetches it over https only, at that one path, with a timeout and a size cap, following redirects only to the domain asked for or a subdomain of it — and it distinguishes a host that answered 404 (absent) from a host that did not answer at all (unreachable). Those two are never collapsed, because "this organisation has no door" and "we could not reach this organisation" need opposite responses.

{ "amount": 2500, "currency": "GBP" }

Capabilities are verbs, not departments

The first refusal that shapes a good door is that capabilities are verbs — quote, book, refund — and never departments — sales, support, finance. The id rule requires a lowercase verb form and rejects a denylist of department words by name. The reason is that a department tells an agent who to talk to, which an agent cannot use; an action tells it what it can do, which it can. A door whose capabilities read like an org chart is a door an agent cannot open.

Endpoints stay on your own domain

The refusal that keeps the gateway safe is that every endpoint’s host must be the document’s own domain or a subdomain of it — never a parent, a sibling, or a stranger. A document may not point agents at another organisation’s endpoints, whatever the commercial arrangement; the other organisation publishes its own door. The rule is deliberately not "same registrable domain": there is no public-suffix list in the checker, so it cannot tell a country-code suffix from an ordinary domain, and rather than guess it refuses parents and siblings too. That same-domain rule is a single shared module, canonical in one repository and vendored byte-identically wherever it is used, so three specifications built to interoperate cannot each implement "same domain" slightly differently — which is exactly the drift the estate had before it was made one function.

Prices, accountability, and refusing to guess

Money in a door is whole minor units beside an explicit currency, and the checker refuses a float, refuses a bare number, refuses an amount with no currency, and refuses a price with no way to pay it. An accountable human is required — a name and a mailbox somebody reads — and the template placeholder is refused, because an interface nobody answers for is one nobody can be asked to stop. Everything else the checker refuses rather than guesses: an unknown key not prefixed x-, and thirteen other refusals, each with a vector that proves it fails for its own rule and no other. The result for an organisation is that a door either validates and is safe to publish or it names precisely what is wrong — the same property this practice wants from every machine surface it ships.

• The lab’s view (planned)FlashyLabs is preparing an engineering companion to this piece at https://flashylabs.com/insights/putting-a-door-on-a-legacy-api — planned, not yet published.
• The studio’s view (planned)The 4 Ventures thesis desk is preparing an investor-lens companion at https://4.ventures/thesis/putting-a-door-on-a-legacy-api — planned, not yet published.