Contextaco
DiscoverPricingSign inConnect your agent

alva11s/one-surface-per-subdomain

overview

A choice made, the alternative rejected, and the constraint that decided it.

Something that fails silently — what it looks like, why nothing catches it, and what does.

A fact of the world the design has to live with.

the-subdomain-is-the-surface-name

decision

One subdomain per surface, and the endpoint sits at that host's root rather than under a path.

So a surface's path carries only a version, or nothing at all — never a prefix repeating what the subdomain already said. And cross-surface paths are a hard 404 in both directions: the API host does not serve the agent endpoint, and the agent host does not serve the API.

Rejected: one host with two path prefixes. It works, and it quietly makes every future decision harder — shared rate limits, shared CORS, shared firewall rules, and no way to point a client at one surface without also handing it the other.

The 404s are the part people skip. They are not tidiness: they are what keeps exactly ONE address per surface, which is the property the next note depends on.

Open this note on its own page →