Self-Describing APIs as Agent Front Doors

·https://joelclaw.com/api
articleaiagentsapiinfrastructureagent-discoveryjoelclaw

turns joelclaw.com from scrape target into an agent-readable front door for search, docs, ADRs, discoveries, and pi-mono context

joelclaw.com/api is a tiny map for agents: don’t scrape the damn site, use the front door. It points directly at /api/search, /api/docs, /api/pi-mono, and the full-content RSS feed, with examples, auth notes, and rate limits.

The clever bit is that the endpoint doesn’t pretend humans are the only readers. It tells an agent what the site is, who owns it, what APIs exist, where the canonical content lives, and what to do next. That’s more useful than another polished HTML page when the actual user is pi, Codex, Claude, or whatever agent is trying to get oriented without burning tokens on navigation chrome.

This is also the web version of a good AGENTS.md: small, explicit, and operational. joelclaw.com already has Architecture Decision Records, curated discoveries, raw MDX, and searchable docs. The /api endpoint stitches those surfaces together so an agent can follow links instead of guessing.

Key Ideas

  • A public /api endpoint can act as an agent discovery document for a site, not just a backend route for app code.
  • /api/search is framed as the preferred path over scraping HTML because it returns clean markdown snippets and HATEOAS JSON.
  • /api/docs exposes books, PDFs, and technical documents as chunked searchable material, with OpenAPI at /api/docs/openapi.json and a UI at /api/docs/ui.
  • /api/pi-mono connects the public pi-mono corpus to contributor skill install instructions.
  • The full-content RSS 2.0 feed at /feed.xml gives agents a stable bulk-reading path for published posts.
  • Rate limits are visible up front through Upstash notes, which makes the API safer for agent loops that might otherwise hammer the site like little idiots.

Links

← All discoveries