API documentation

GET /api/status

Returns public service availability as JSON.

POST /api/contact

Accepts JSON fields for name, email, and message. Requests must originate from this site, are rate limited, and are delivered only to the configured site owner. Browser agents should use the visible contact form rather than calling this endpoint cross-origin.

POST /mcp

A remote Model Context Protocol server (JSON-RPC 2.0 over Streamable HTTP, protocol version 2025-06-18). Exposes one read-only tool, get-portfolio-profile, returning the same profile data as the markdown rendition of this site. A machine-readable description of the server is available at /mcp/manifest.json.

Every request must send Content-Type: application/json and Accept: application/json, text/event-stream. Every request except initialize must also send MCP-Protocol-Version: 2025-06-18; requests missing it or naming an unsupported version are rejected with a JSON-RPC error.

Complete the Streamable HTTP handshake by calling initialize, then sending the notifications/initialized notification (a JSON-RPC request with no id, which receives no response) before calling tools/list or tools/call.

The same Streamable HTTP surface is also answered at /.well-known/mcp, so an agent that discovers the server at the well-known path can complete the live handshake there without following the manifest to /mcp.

Versioning and deprecation

Every REST response carries an API-Version header with the contract version that served it. Clients may send API-Version: 1 to pin a version; supported versions are 1. A request naming any other version is rejected with 400 UNSUPPORTED_API_VERSION.

Breaking changes ship under a new API version. Deprecated operations and fields remain available for at least 90 days, are marked "deprecated: true" in /openapi.json, and return Deprecation: true with a Sunset header naming the removal date until they are removed.

Errors

Every non-2xx REST response uses the typed error object defined as Error in the OpenAPI document, including requests to unknown /api/ paths and unsupported HTTP methods. Each error carries a stable code, a human-readable message, and a resolution hint.

{
  "success": false,
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "GET is not supported for /api/contact.",
    "resolution": "Send POST to /api/contact"
  }
}

POST /a2a

A stateless A2A agent (Agent2Agent protocol 1.0, JSON-RPC 2.0 over HTTPS) that answers SendMessage with the public portfolio profile. Its Agent Card is served at /.well-known/agent-card.json.

Every request must send Content-Type: application/json and A2A-Version: 1.0. A missing or other version is answered with a VersionNotSupportedError (-32009). ListTasks returns an empty list, while GetTask, CancelTask, SendStreamingMessage, and GetExtendedAgentCard report the corresponding A2A errors because this agent keeps no task state and supports neither streaming nor extended cards.

Discovery documents

Machine-readable metadata for the surfaces above is published at well-known paths.

• /.well-known/ai-catalog.json : Agentic Resource Discovery manifest.
• /.well-known/mcp : MCP server manifest on GET and the live MCP Streamable HTTP handshake on POST (same surface as /mcp).
• /.well-known/mcp/server-card.json and /mcp/server-card: MCP Server Card (SEP-2127).
• /.well-known/agent-card.json : A2A Agent Card.
• /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server : RFC 9728 and RFC 8414 metadata naming this origin as its only authorization server and advertising an anonymous-only agent_auth registration method; every public endpoint is unauthenticated. See /auth.md.
• /.well-known/api-catalog and /.well-known/agent-skills/index.json : RFC 9727 linkset and Agent Skills index.