Self-Documenting Endpoints: One URL for Humans and Agents

Documentation usually begins as a promise and decays into folklore.

At first, the docs match reality. The field names are right. The examples work. The required fields are marked. Then the product changes. A field becomes optional. A new enum value appears. A validation rule moves from frontend to backend. Someone updates the UI. Someone forgets to update the docs.

Nobody is careless. The system is just split across too many places.

Forms suffer from this constantly because the thing being documented is often not treated as a first-class object. There is a UI. There is a backend handler. There may be a validation schema somewhere. There may be a help page. There may be a README. There may be an agent trying to infer the shape by reading a webpage.

Postbox takes a different position: the endpoint should document itself.

The endpoint already knows

A form endpoint is not just a destination for POST requests. It already knows the contract. It knows the field names, the field types, the validation rules, the visibility, and the authentication requirements. If it can reject invalid submissions, it has enough information to explain valid ones.

So why make developers, agents, or future teammates look anywhere else?

In Postbox, every form endpoint has multiple faces:

• GET with Accept: application/json returns the schema.
• GET with Accept: text/html returns human-readable endpoint documentation.
• POST with Content-Type: application/json submits data.

Same URL. Different intent. Same underlying contract.

That small design choice changes the integration experience completely.

For humans, it removes the scavenger hunt

A developer opening an endpoint in the browser should not hit a blank page, a 404, or a mysterious JSON blob with no context. They should see what the endpoint is, what it accepts, which fields are required, and how to submit to it.

That is not a full product manual. It is not trying to replace deeper documentation. It is the minimum viable truth at the point of use.

The closer documentation lives to the thing it documents, the harder it is for them to drift apart.

A self-documenting endpoint becomes a little reference card attached to the contract itself. You do not have to ask where the schema lives. You ask the form.

For agents, it removes guesswork

Agents should not have to scrape a visual form and infer intent from labels. That is fragile and unnecessary. A browser layout is optimized for a human eye. A schema is optimized for a machine that needs to act correctly.

When an agent wants to submit to a Postbox form, it can discover the schema at runtime:

GET /api/.../f/contact
Accept: application/json

The response tells it the method, content type, fields, types, rules, and authentication requirements. The agent constructs a valid payload and posts it.

No SDK. No hardcoded field names. No separate documentation lookup.

This is what we mean when we say Postbox is agent-native. The agent is not a weird edge case bolted onto a human workflow. It is a legitimate client of the same contract.

Humans and agents should not need different truth

A common failure mode in software is parallel truth.

The UI says one thing. The API docs say another. The backend enforces a third. The agent prompt includes a fourth. The company wiki remembers a fifth. Eventually nobody knows which one is real.

Self-documenting endpoints reduce that surface area. They do not eliminate all documentation, but they make the contract inspectable at the source. If you need to know what a form accepts, ask the form.

That matters even more as forms become part of agent workflows. An agent might create a form, hand its endpoint to another agent, collect submissions, summarize the results, and draft replies — all without a person ever opening the dashboard. That workflow only works if the contract is discoverable.

Honeypots are a useful example

Honeypot fields show why endpoint documentation needs nuance.

A honeypot field exists in the owner-facing schema. It is a real validation rule. Bots that blindly fill every field should hit it. Humans should never see it. Agents should never be told to fill it.

So the discovery response omits honeypot fields. The contract exposed to submitters includes what legitimate clients should send, not every internal trick the owner configured.

That distinction matters. Self-documenting does not mean “dump every implementation detail.” It means “reveal the actionable contract to the audience asking.”

This is not just convenience

It is tempting to treat self-documenting endpoints as a developer-experience flourish. Nice, but not essential.

We think it is more fundamental than that.

A self-documenting endpoint is a way to make the web more legible to non-human clients without making it worse for human ones. It is a way to preserve the simplicity of URLs while making those URLs richer. It is a way to stop treating documentation as a separate artifact that must be chased and maintained.

Most importantly, it is a way to make forms act like APIs.

An API that cannot tell you what it accepts is incomplete. A form endpoint is no different.

The rule of thumb

If a system can reject bad input, it should be able to describe good input.

Postbox applies that rule to forms. The endpoint is not just where data goes. It is where the contract lives, where the contract is explained, and where the contract is enforced.

That is the shape we think form infrastructure should have.

One URL. Two audiences. Same contract.

See the feature overview for self-documenting endpoints, or read the broader thesis behind schema-as-contract forms.