Developer & Agent Documentation

Machine-readable discovery endpoints for AI agents, MCP clients, and API integrators. Canonical origin: https://www.seanguillermo.com

Discovery endpoints

  • OpenAPI 3.1

    Contact, newsletter, services, health, and MCP endpoints — /openapi.json

  • API Catalog (RFC 9727)

    JSON catalog of public APIs — /.well-known/api-catalog

  • MCP Server Card

    SEP-1649 discovery for /api/mcp — /.well-known/mcp/server-card.json

  • A2A Agent Card

    Agent2Agent capability manifest — /.well-known/agent-card.json

  • agents.json

    Directory of agent endpoints — /.well-known/agents.json

  • AI Catalog

    URN:AIR discovery entries — /.well-known/ai-catalog.json

  • Agent Skills Index

    Verifiable SKILL.md directory — /.well-known/agent-skills/index.json

  • AGENTS.md

    Root agent guide and etiquette — /AGENTS.md

  • llms.txt

    LLM-friendly site map — /llms.txt

  • auth.md

    OAuth and agent authentication — /auth.md

MCP transport

Streamable HTTP endpoint at /api/mcp. Tools: submit_contact, list_insights. OAuth metadata at /.well-known/oauth-authorization-server.

Agent view

Add ?mode=agent to any page URL for a structured JSON view of that page: title, summary, sections, links, and available actions. Add &format=markdown (or send Accept: text/markdown) for markdown. Example: /services?mode=agent.

Errors

Every API error is application/problem+json (RFC 9457) with type, title, status, detail, instance, and a stable code. Validation errors add an errors array of { field, message }. Unknown /api/* paths return a 404 problem, never an HTML page. Quote the requestId (also sent as X-Request-Id) when reporting a failure.

  • bad-request (400) — Body is not a JSON object
  • validation-failed (400) — A required field is missing or invalid
  • unauthorized (401) — Sign-in required
  • forbidden (403) — Signed in, but not allowed
  • not-found (404) — No endpoint at this path
  • unsupported-media-type (415) — Send JSON or an HTML form body
  • rate-limited (429) — Too many requests; wait for Retry-After seconds
  • server-error (500) — Unexpected failure; retry later

Rate limits

Limits are per client IP: 5 requests per minute for /api/contact and /api/newsletter, 30 for /api/mcp, and 60 for other endpoints. Every response sends RateLimit-Policy and RateLimit (IETF draft) plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 also sends Retry-After.

Versioning & deprecation policy

The current API version is 1, sent on every response as API-Version: 1. /api/v1/* is a stable alias of /api/*; use it for long-lived integrations. Additive changes (new endpoints, new optional fields) ship in place. Breaking changes ship only under a new major prefix such as /api/v2/*.

A deprecated endpoint keeps working for at least 6 months. During that time its responses carry a Deprecation header (RFC 9745), a Sunset header (RFC 8594) with the removal date, and a Link header with rel="deprecation" pointing to this section. The change is also listed in /openapi.json. No endpoint is deprecated today.

Contact Sean