The best agent onboarding is a URL

Most API onboarding still assumes a human is sitting there with a dashboard open.

That is fine for humans. It is awkward for agents. An agent does not need a hero section, three pricing cards, and a modal asking it to book a demo. It needs to know what it can read, what requires a key, what actions are safe, and where the contract lives.

Asha.News gets this small product decision right. The public agent guide at /llms.txt lists the read endpoints, the OpenAPI URL, the feed, digest, search, share-pack, coverage, source health, generated briefs, and the two public actions an agent can take without a key. The OpenAPI document describes itself as a read-focused contract for agents and digest consumers, with no-key share-link creation and double opt-in newsletter signup.

That is the pattern worth stealing: public discovery first, credentials later.

No-key reads lower the temperature

A lot of agent products treat authentication as the first step. That sounds secure, but it often means the agent cannot even learn the shape of the system without a human pasting credentials somewhere.

Asha.News separates the harmless surface from the privileged one. Public reads need no key. The guide says browsers may read those endpoints cross-origin. Publishing generated briefs needs a scoped key. Newsletter signup does not activate anything until the address owner clicks the emailed confirmation link.

That is a cleaner trust boundary than "give the agent an API key and hope the prompt behaves."

The result is calmer onboarding. An agent can inspect the public feed at /api/v1/feed, read the public digest at /api/v1/digest, check the OpenAPI contract at /api/v1/openapi, and decide whether it has enough context for the user's task. If it needs to submit or edit generated briefs, that is a different permission class.

Good agent UX starts by not asking for a secret too early.

The contract is part of the interface

For humans, documentation is supporting material. For agents, documentation is the interface.

The Asha.News guide is useful because it is blunt. It names endpoints. It says no API key is required for public reads. It tells agents to prefer archived Asha data over scraping, preserve citations and source URLs, disclose stale or fallback data, and never ask for passwords, keys, or secrets.

That reads like product copy for a machine. Which is exactly what it should be.

The OpenAPI document does the other half of the job. It gives a stable schema to clients that do not want to scrape docs. It also makes the security model visible: bearer auth exists, agent keys exist, and public operations are explicitly scoped. An agent can route itself without pretending every endpoint has the same risk.

This is where many "agent-ready" products are still weak. They add an MCP server or a chat widget, but the underlying contract is vague. The agent has to infer whether an action is safe. Inference is where expensive mistakes live.

Safe actions should be boring

The two no-key actions are the interesting detail.

Minting a share link is low risk if the product controls the destination and status endpoint. Starting a newsletter signup is low risk because the subscription stays inactive until the email owner confirms. Neither action requires handing the agent a broad credential.

That is how agent actions should feel: narrow, reversible or gated, and boring to audit.

The temptation is to make the agent powerful immediately. Let it publish. Let it mutate records. Let it call private endpoints because friction is bad for demos. The more useful product move is to give it safe affordances first, then make every higher-risk action cross an explicit permission boundary.

Asha.News is not perfect because no live system is perfect. But the shape is right. Public facts are easy to read. Source trails stay visible. Riskier operations require scoped credentials or human confirmation paths.

That is the agent onboarding pattern I want more products to copy: a URL the agent can read, a contract it can trust, and permissions that arrive only when the task actually needs them.