News APIs need empty states for agents

A good news API should sometimes make the agent feel stuck.

That sounds backwards. The whole point of an endpoint like Asha.News is to give automation something cleaner than a tab full of publisher pages: a title, summary, source URL, timestamps, archive status, and enough metadata to decide whether the story is fresh. The public feed already does that. The digest does it at the cluster level. The share-pack endpoint is pointed at the same idea for social workflows.

The missing product surface is the refusal.

Sources: Asha.News public feed, Asha.News public digest, Asha.News share-pack endpoint, Asha.News Agent API page.

The payload can be valid and still unsafe

A machine can check whether a response has title, summary, url, published_at, and source. That is easy. It can check whether the linked page returns 200. Also easy.

The harder question is whether the result answers the request closely enough to use in public.

This matters more for news than for most product data. A product catalog can return a near match and the user will probably notice. A news automation can return a near match and create a public post with a clean owned link attached to the wrong event. The shape looks right, so the mistake gets laundered through structure.

Asha.News is already better than a normal RSS scrape because it exposes freshness and source fields instead of hiding them in prose. The public feed I checked today included source publication time, Asha first-seen time, last-checked time, canonical URL, image status, archive extraction status, and a freshness label. That is the right direction.

But a citation product needs one more thing: an explicit answer to "safe to cite for this query?"

Empty is a feature

Most search products treat an empty state like failure. For agents, it is often the safer outcome.

If the query asks for Grand Canyon flash flood and the best cluster is about a different flood, the endpoint should not hide behind semantic similarity. It should say the named entities did not match. If the query asks for a person, place, law, model name, or incident, those terms should become part of the receipt.

A useful response would expose:

• matched terms and missing terms;
• whether the match came from exact text search, cluster search, or semantic fallback;
• source count and source names;
• first-seen and last-checked timestamps;
• a citation-safety flag for public use.

That last field sounds bureaucratic until a scheduled social agent gets it wrong.

Agents need slower confidence

The dangerous version of automation is not the one that fails loudly. It is the one that produces a neat packet too quickly.

A news API for agents should slow confidence down. It should make the caller prove that the result matches the request, the page is live, the citations are visible, and the story is specific enough to carry a public claim. If any part is weak, return the candidate, but mark it as weak.

That does not make Asha.News less useful. It makes it more useful for the kind of system it is trying to serve.

People can skim and catch mismatch by feel. Agents need mismatch designed into the response.